1QDialog(3qt)                                                      QDialog(3qt)
2
3
4

NAME

6       QDialog - The base class of dialog windows
7

SYNOPSIS

9       #include <qdialog.h>
10
11       Inherits QWidget.
12
13       Inherited by QColorDialog, QErrorMessage, QFileDialog, QFontDialog,
14       QInputDialog, QMessageBox, QMotifDialog, QProgressDialog, QTabDialog,
15       and QWizard.
16
17   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
33   Public Slots
34       int exec ()
35
36   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
41   Protected Members
42       void setResult ( int i )
43
44   Protected Slots
45       virtual void done ( int r )
46       virtual void accept ()
47       virtual void reject ()
48       void showExtension ( bool showIt )
49

DESCRIPTION

51       The QDialog class is the base class of dialog windows.
52
53       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
59       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
72       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
79       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

Modeless Dialogs

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
94       Modeless dialogs are displayed using show(), which returns control to
95       the caller immediately.
96

Default button

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

Escape Key

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

Extensibility

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

Return value (modal dialogs)

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

Examples

133       A modal dialog.
134
135               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
147       A modeless dialog. After the show() call, control returns to the main
148       event loop.
149
150           int main( int argc, char **argv )
151           {
152               QApplication a( argc, argv );
153
154               int scale = 10;
155
156               LifeDialog *life = new LifeDialog( scale );
157               a.setMainWidget( life );
158               life->setCaption("Qt Example - Life");
159               life->show();
160
161               return a.exec();
162           }
163
164       See also QTabDialog, QWidget, QProgressDialog, GUI Design Handbook:
165       Dialogs, Standard, Abstract Widget Classes, and Dialog Classes.
166
167   Member Type Documentation

QDialog::DialogCode

169       The value returned by a modal dialog.
170
171       QDialog::Accepted
172
173       QDialog::Rejected
174

MEMBER FUNCTION DOCUMENTATION

explicit QDialog::QDialog ( QWidget * parent = 0, const char * name = 0, bool

177       modal = FALSE, WFlags f = 0 )
178       Constructs a dialog called name, with parent parent.
179
180       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
184       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
189       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
194       See also QWidget::setWFlags() and Qt::WidgetFlags.
195

QDialog::~QDialog ()

197       Destroys the QDialog, deleting all its children.
198

void QDialog::accept () [virtual protected slot]

200       Hides the modal dialog and sets the result code to Accepted.
201
202       See also reject() and done().
203
204       Examples:
205

void QDialog::done ( int r ) [virtual protected slot]

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
211       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
216       See also accept(), reject(), QApplication::mainWidget(), and
217       QApplication::quit().
218

int QDialog::exec () [slot]

220       Shows the dialog as a modal dialog, blocking until the user closes it.
221       The function returns a DialogCode result.
222
223       Users cannot interact with any other window in the same application
224       until they close the dialog.
225
226       See also show() and result().
227
228       Examples:
229

QWidget * QDialog::extension () const

231       Returns the dialog's extension or 0 if no extension has been defined.
232
233       See also setExtension().
234

bool QDialog::isModal () const

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

bool QDialog::isSizeGripEnabled () const

240       Returns TRUE if the size grip is enabled; otherwise returns FALSE. See
241       the "sizeGripEnabled" property for details.
242

Orientation QDialog::orientation () const

244       Returns the dialog's extension orientation.
245
246       See also setOrientation().
247

void QDialog::reject () [virtual protected slot]

249       Hides the modal dialog and sets the result code to Rejected.
250
251       See also accept() and done().
252

int QDialog::result () const

254       Returns the modal dialog's result code, Accepted or Rejected.
255
256       Do not call this function if the dialog was constructed with the
257       WDestructiveClose flag.
258

void QDialog::setExtension ( QWidget * extension )

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
264       This function must only be called while the dialog is hidden.
265
266       See also showExtension(), setOrientation(), and extension().
267

void QDialog::setModal ( bool modal )

269       Sets whether show() should pop up the dialog as modal or modeless to
270       modal. See the "modal" property for details.
271

void QDialog::setOrientation ( Orientation orientation )

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
277       See also orientation() and setExtension().
278

void QDialog::setResult ( int i ) [protected]

280       Sets the modal dialog's result code to i.
281

void QDialog::setSizeGripEnabled ( bool )

283       Sets whether the size grip is enabled. See the "sizeGripEnabled"
284       property for details.
285

void QDialog::show () [virtual]

287       Shows the dialog as a modeless dialog. Control returns immediately to
288       the calling code.
289
290       The dialog will be modal or modeless according to the value of the
291       modal property.
292
293       See also exec() and modal.
294
295       Examples:
296
297       Reimplemented from QWidget.
298

void QDialog::showExtension ( bool showIt ) [protected slot]

300       If showIt is TRUE, the dialog's extension is shown; otherwise the
301       extension is hidden.
302
303       This slot is usually connected to the QButton::toggled() signal of a
304       QPushButton.
305
306       A dialog with a visible extension is not resizeable.
307
308       See also show(), setExtension(), and setOrientation().
309
310   Property Documentation

bool modal

312       This property holds whether show() should pop up the dialog as modal or
313       modeless.
314
315       By default, this property is false and show() pops up the dialog as
316       modeless.
317
318       exec() ignores the value of this property and always pops up the dialog
319       as modal.
320
321       See also show() and exec().
322
323       Set this property's value with setModal() and get this property's value
324       with isModal().
325

bool sizeGripEnabled

327       This property holds whether the size grip is enabled.
328
329       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
332       Set this property's value with setSizeGripEnabled() and get this
333       property's value with isSizeGripEnabled().
334
335

SEE ALSO

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

AUTHOR

346       Generated automatically from the source code.
347

BUGS

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
353       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
359       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).
362
363
364
365Trolltech AS                    2 February 2007                   QDialog(3qt)
Impressum