diff options
Diffstat (limited to 'doc/html/qdialog.html')
| -rw-r--r-- | doc/html/qdialog.html | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/doc/html/qdialog.html b/doc/html/qdialog.html new file mode 100644 index 0000000..cf0a168 --- /dev/null +++ b/doc/html/qdialog.html @@ -0,0 +1,355 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/dialogs/qdialog.cpp:59 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>QDialog Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QDialog Class Reference</h1> + +<p>The QDialog class is the base class of dialog windows. +<a href="#details">More...</a> +<p><tt>#include <<a href="qdialog-h.html">qdialog.h</a>></tt> +<p>Inherits <a href="qwidget.html">QWidget</a>. +<p>Inherited by <a href="qcolordialog.html">QColorDialog</a>, <a href="qerrormessage.html">QErrorMessage</a>, <a href="qfiledialog.html">QFileDialog</a>, <a href="qfontdialog.html">QFontDialog</a>, <a href="qinputdialog.html">QInputDialog</a>, <a href="qmessagebox.html">QMessageBox</a>, <a href="qmotifdialog.html">QMotifDialog</a>, <a href="qprogressdialog.html">QProgressDialog</a>, <a href="qtabdialog.html">QTabDialog</a>, and <a href="qwizard.html">QWizard</a>. +<p><a href="qdialog-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn>explicit <a href="#QDialog"><b>QDialog</b></a> ( QWidget * parent = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 )</li> +<li class=fn><a href="#~QDialog"><b>~QDialog</b></a> ()</li> +<li class=fn>enum <a href="#DialogCode-enum"><b>DialogCode</b></a> { Rejected, Accepted }</li> +<li class=fn>int <a href="#result"><b>result</b></a> () const</li> +<li class=fn>virtual void <a href="#show"><b>show</b></a> ()</li> +<li class=fn>void <a href="#setOrientation"><b>setOrientation</b></a> ( Orientation orientation )</li> +<li class=fn>Orientation <a href="#orientation"><b>orientation</b></a> () const</li> +<li class=fn>void <a href="#setExtension"><b>setExtension</b></a> ( QWidget * extension )</li> +<li class=fn>QWidget * <a href="#extension"><b>extension</b></a> () const</li> +<li class=fn>void <a href="#setSizeGripEnabled"><b>setSizeGripEnabled</b></a> ( bool )</li> +<li class=fn>bool <a href="#isSizeGripEnabled"><b>isSizeGripEnabled</b></a> () const</li> +<li class=fn>void <a href="#setModal"><b>setModal</b></a> ( bool modal )</li> +<li class=fn>bool <a href="#isModal"><b>isModal</b></a> () const</li> +</ul> +<h2>Public Slots</h2> +<ul> +<li class=fn>int <a href="#exec"><b>exec</b></a> ()</li> +</ul> +<h2>Properties</h2> +<ul> +<li class=fn>bool <a href="#modal-prop"><b>modal</b></a> - whether show() should pop up the dialog as modal or modeless</li> +<li class=fn>bool <a href="#sizeGripEnabled-prop"><b>sizeGripEnabled</b></a> - whether the size grip is enabled</li> +</ul> +<h2>Protected Members</h2> +<ul> +<li class=fn>void <a href="#setResult"><b>setResult</b></a> ( int i )</li> +</ul> +<h2>Protected Slots</h2> +<ul> +<li class=fn>virtual void <a href="#done"><b>done</b></a> ( int r )</li> +<li class=fn>virtual void <a href="#accept"><b>accept</b></a> ()</li> +<li class=fn>virtual void <a href="#reject"><b>reject</b></a> ()</li> +<li class=fn>void <a href="#showExtension"><b>showExtension</b></a> ( bool showIt )</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + +The QDialog class is the base class of dialog windows. +<p> + + +<p> A dialog window is a top-level window mostly used for short-term +tasks and brief communications with the user. QDialogs may be +modal or modeless. QDialogs support <a href="#extensibility">extensibility</a> and can provide a <a href="#return">return + value</a>. They can have <a href="#default">default + buttons</a>. QDialogs can also have a <a href="qsizegrip.html">QSizeGrip</a> in their +lower-right corner, using <a href="#setSizeGripEnabled">setSizeGripEnabled</a>(). +<p> Note that QDialog uses the parent widget slightly differently from +other classes in Qt. A dialog is always a top-level widget, but if +it has a parent, its default location is centered on top of the +parent's top-level widget (if it is not top-level itself). It will +also share the parent's taskbar entry. +<p> <a name="modal"></a> +<h3> Modal Dialogs +</h3> +<a name="1"></a><p> A <b>modal</b> dialog is a dialog that blocks input to other +visible windows in the same application. Users must finish +interacting with the dialog and close it before they can access +any other window in the application. Dialogs that are used to +request a file name from the user or that are used to set +application preferences are usually modal. +<p> The most common way to display a modal dialog is to call its +<a href="#exec">exec</a>() function. When the user closes the dialog, exec() will +provide a useful <a href="#return">return value</a>. Typically we +connect a default button, e.g. "OK", to the <a href="#accept">accept</a>() slot and a +"Cancel" button to the <a href="#reject">reject</a>() slot, to get the dialog to close +and return the appropriate value. Alternatively you can connect to +the <a href="#done">done</a>() slot, passing it <a href="#DialogCode-enum">Accepted</a> or <a href="#DialogCode-enum">Rejected</a>. +<p> An alternative is to call <a href="#setModal">setModal</a>(TRUE), then <a href="#show">show</a>(). Unlike +exec(), show() returns control to the caller immediately. Calling +setModal(TRUE) is especially useful for progress dialogs, where +the user must have the ability to interact with the dialog, e.g. +to cancel a long running operation. If you use show() and +setModal(TRUE) together you must call +<a href="qapplication.html#processEvents">QApplication::processEvents</a>() periodically during processing to +enable the user to interact with the dialog. (See <a href="qprogressdialog.html">QProgressDialog</a>.) +<p> <a name="modeless"></a> +<h3> Modeless Dialogs +</h3> +<a name="1-1"></a><p> A <b>modeless</b> dialog is a dialog that operates +independently of other windows in the same application. Find and +replace dialogs in word-processors are often modeless to allow the +user to interact with both the application's main window and with +the dialog. +<p> Modeless dialogs are displayed using show(), which returns control +to the caller immediately. +<p> <a name="default"></a> +<h3> Default button +</h3> +<a name="1-2"></a><p> A dialog's <em>default</em> button is the button that's pressed when the +user presses Enter (Return). This button is used to signify that +the user accepts the dialog's settings and wants to close the +dialog. Use <a href="qpushbutton.html#setDefault">QPushButton::setDefault</a>(), <a href="qpushbutton.html#isDefault">QPushButton::isDefault</a>() +and <a href="qpushbutton.html#autoDefault">QPushButton::autoDefault</a>() to set and control the dialog's +default button. +<p> <a name="escapekey"></a> +<h3> Escape Key +</h3> +<a name="1-3"></a><p> If the user presses the Esc key in a dialog, <a href="#reject">QDialog::reject</a>() +will be called. This will cause the window to close: the <a href="qcloseevent.html">closeEvent</a> cannot be <a href="qcloseevent.html#ignore">ignored</a>. +<p> <a name="extensibility"></a> +<h3> Extensibility +</h3> +<a name="1-4"></a><p> Extensibility is the ability to show the dialog in two ways: a +partial dialog that shows the most commonly used options, and a +full dialog that shows all the options. Typically an extensible +dialog will initially appear as a partial dialog, but with a +"More" toggle button. If the user presses the "More" button down, +the full dialog will appear. The extension widget will be resized +to its <a href="qwidget.html#sizeHint">sizeHint</a>(). If orientation is <a href="qt.html#Orientation-enum">Horizontal</a> the extension +widget's <a href="qwidget.html#height">height</a>() will be expanded to the height() of the dialog. +If the orientation is <a href="qt.html#Orientation-enum">Vertical</a> the extension widget's <a href="qwidget.html#width">width</a>() +will be expanded to the width() of the dialog. Extensibility is +controlled with <a href="#setExtension">setExtension</a>(), <a href="#setOrientation">setOrientation</a>() and +<a href="#showExtension">showExtension</a>(). +<p> <a name="return"></a> +<h3> Return value (modal dialogs) +</h3> +<a name="1-5"></a><p> Modal dialogs are often used in situations where a return value is +required, e.g. to indicate whether the user pressed "OK" or +"Cancel". A dialog can be closed by calling the <a href="#accept">accept</a>() or the +<a href="#reject">reject</a>() slots, and <a href="#exec">exec</a>() will return <a href="#DialogCode-enum">Accepted</a> or <a href="#DialogCode-enum">Rejected</a> +as appropriate. The exec() call returns the result of the dialog. +The result is also available from <a href="#result">result</a>() if the dialog has not +been destroyed. If the <a href="qt.html#WidgetFlags-enum">WDestructiveClose</a> flag is set, the +dialog is deleted after exec() returns. +<p> <a name="examples"></a> +<h3> Examples +</h3> +<a name="1-6"></a><p> A modal dialog. +<p> + +<pre> <a href="qfiledialog.html">QFileDialog</a> *dlg = new <a href="qfiledialog.html">QFileDialog</a>( workingDirectory, + <a href="qstring.html#QString-null">QString::null</a>, 0, 0, TRUE ); + <a name="x2130"></a> dlg-><a href="qwidget.html#setCaption">setCaption</a>( QFileDialog::<a href="qobject.html#tr">tr</a>( "Open" ) ); + <a name="x2128"></a> dlg-><a href="qfiledialog.html#setMode">setMode</a>( QFileDialog::ExistingFile ); + <a href="qstring.html">QString</a> result; + <a name="x2126"></a> if ( dlg-><a href="#exec">exec</a>() == QDialog::<a href="#DialogCode-enum">Accepted</a> ) { + <a name="x2127"></a> result = dlg-><a href="qfiledialog.html#selectedFile">selectedFile</a>(); + <a name="x2129"></a> workingDirectory = dlg-><a href="qfiledialog.html#url">url</a>(); + } + delete dlg; + return result; +</pre> +<p> A modeless dialog. After the <a href="#show">show</a>() call, control returns to the main +event loop. + + +<pre> int main( int argc, char **argv ) + { + <a href="qapplication.html">QApplication</a> a( argc, argv ); +</pre><pre> int scale = 10; +</pre><pre> LifeDialog *life = new LifeDialog( scale ); + <a name="x2133"></a> a.<a href="qapplication.html#setMainWidget">setMainWidget</a>( life ); + <a name="x2134"></a> life-><a href="qwidget.html#setCaption">setCaption</a>("Qt Example - Life"); + <a name="x2135"></a> life-><a href="qwidget.html#show">show</a>(); +</pre><pre> <a name="x2132"></a> return a.<a href="qapplication.html#exec">exec</a>(); + } +</pre> +<p> <p>See also <a href="qtabdialog.html">QTabDialog</a>, <a href="qwidget.html">QWidget</a>, <a href="qprogressdialog.html">QProgressDialog</a>, <a href="guibooks.html#fowler">GUI Design Handbook: Dialogs, Standard</a>, <a href="abstractwidgets.html">Abstract Widget Classes</a>, and <a href="dialogs.html">Dialog Classes</a>. + +<hr><h2>Member Type Documentation</h2> +<h3 class=fn><a name="DialogCode-enum"></a>QDialog::DialogCode</h3> +<p> The value returned by a modal dialog. +<ul> +<li><tt>QDialog::Accepted</tt> +<li><tt>QDialog::Rejected</tt> +</ul><p> +<hr><h2>Member Function Documentation</h2> +<h3 class=fn>explicit <a name="QDialog"></a>QDialog::QDialog ( <a href="qwidget.html">QWidget</a> * parent = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 ) +</h3> +Constructs a dialog called <em>name</em>, with parent <em>parent</em>. +<p> A dialog is always a top-level widget, but if it has a parent, its +default location is centered on top of the parent. It will also +share the parent's taskbar entry. +<p> The widget flags <em>f</em> are passed on to the <a href="qwidget.html">QWidget</a> constructor. +If, for example, you don't want a What's This button in the titlebar +of the dialog, pass WStyle_Customize | WStyle_NormalBorder | +WStyle_Title | WStyle_SysMenu in <em>f</em>. +<p> <b>Warning:</b> In Qt 3.2, the <em>modal</em> flag is obsolete. There is now a +<a href="#setModal">setModal</a>() function that can be used for obtaining a modal behavior +when calling <a href="#show">show</a>(). This is rarely needed, because modal dialogs +are usually invoked using <a href="#exec">exec</a>(), which ignores the <em>modal</em> flag. +<p> <p>See also <a href="qwidget.html#setWFlags">QWidget::setWFlags</a>() and <a href="qt.html#WidgetFlags-enum">Qt::WidgetFlags</a>. + +<h3 class=fn><a name="~QDialog"></a>QDialog::~QDialog () +</h3> +Destroys the QDialog, deleting all its children. + +<h3 class=fn>void <a name="accept"></a>QDialog::accept ()<tt> [virtual protected slot]</tt> +</h3> +Hides the modal dialog and sets the result code to <a href="#DialogCode-enum">Accepted</a>. +<p> <p>See also <a href="#reject">reject</a>() and <a href="#done">done</a>(). + +<p>Examples: <a href="tutorial2-08.html#x2604">chart/setdataform.cpp</a> and <a href="distributor-example.html#x2654">distributor/distributor.ui.h</a>. +<h3 class=fn>void <a name="done"></a>QDialog::done ( int r )<tt> [virtual protected slot]</tt> +</h3> Closes the dialog and sets its result code to <em>r</em>. If this dialog +is shown with <a href="#exec">exec</a>(), <a href="#done">done</a>() causes the local event loop to finish, +and exec() to return <em>r</em>. +<p> As with <a href="qwidget.html#close">QWidget::close</a>(), done() deletes the dialog if the <a href="qt.html#WidgetFlags-enum">WDestructiveClose</a> flag is set. If the dialog is the application's +main widget, the application terminates. If the dialog is the +last window closed, the <a href="qapplication.html#lastWindowClosed">QApplication::lastWindowClosed</a>() signal is +emitted. +<p> <p>See also <a href="#accept">accept</a>(), <a href="#reject">reject</a>(), <a href="qapplication.html#mainWidget">QApplication::mainWidget</a>(), and <a href="qapplication.html#quit">QApplication::quit</a>(). + +<h3 class=fn>int <a name="exec"></a>QDialog::exec ()<tt> [slot]</tt> +</h3> +Shows the dialog as a <a href="#modal">modal</a> dialog, +blocking until the user closes it. The function returns a <a href="#DialogCode-enum">DialogCode</a> result. +<p> Users cannot interact with any other window in the same +application until they close the dialog. +<p> <p>See also <a href="#show">show</a>() and <a href="#result">result</a>(). + +<p>Examples: <a href="canvas-chart-example.html#x2877">chart/chartform.cpp</a>, <a href="motif-dialog-example.html#x2706">dialog/mainwindow.cpp</a>, <a href="i18n-example.html#x1936">i18n/main.cpp</a>, <a href="ftpclient-example.html#x739">network/ftpclient/ftpmainwindow.ui.h</a>, <a href="qdialog.html#x2126">network/networkprotocol/view.cpp</a>, <a href="qdir-example.html#x1812">qdir/qdir.cpp</a>, and <a href="wizard-example.html#x16">wizard/main.cpp</a>. +<h3 class=fn><a href="qwidget.html">QWidget</a> * <a name="extension"></a>QDialog::extension () const +</h3> +Returns the dialog's extension or 0 if no extension has been +defined. +<p> <p>See also <a href="#setExtension">setExtension</a>(). + +<h3 class=fn>bool <a name="isModal"></a>QDialog::isModal () const +</h3><p>Returns TRUE if <a href="#show">show</a>() should pop up the dialog as modal or modeless; otherwise returns FALSE. +See the <a href="qdialog.html#modal-prop">"modal"</a> property for details. +<h3 class=fn>bool <a name="isSizeGripEnabled"></a>QDialog::isSizeGripEnabled () const +</h3><p>Returns TRUE if the size grip is enabled; otherwise returns FALSE. +See the <a href="qdialog.html#sizeGripEnabled-prop">"sizeGripEnabled"</a> property for details. +<h3 class=fn><a href="qt.html#Orientation-enum">Orientation</a> <a name="orientation"></a>QDialog::orientation () const +</h3> +Returns the dialog's extension orientation. +<p> <p>See also <a href="#setOrientation">setOrientation</a>(). + +<h3 class=fn>void <a name="reject"></a>QDialog::reject ()<tt> [virtual protected slot]</tt> +</h3> +Hides the modal dialog and sets the result code to <a href="#DialogCode-enum">Rejected</a>. +<p> <p>See also <a href="#accept">accept</a>() and <a href="#done">done</a>(). + +<h3 class=fn>int <a name="result"></a>QDialog::result () const +</h3> + +<p> Returns the modal dialog's result code, <a href="#DialogCode-enum">Accepted</a> or <a href="#DialogCode-enum">Rejected</a>. +<p> Do not call this function if the dialog was constructed with the <a href="qt.html#WidgetFlags-enum">WDestructiveClose</a> flag. + +<h3 class=fn>void <a name="setExtension"></a>QDialog::setExtension ( <a href="qwidget.html">QWidget</a> * extension ) +</h3> +Sets the widget, <em>extension</em>, to be the dialog's extension, +deleting any previous extension. The dialog takes ownership of the +extension. Note that if 0 is passed any existing extension will be +deleted. +<p> This function must only be called while the dialog is hidden. +<p> <p>See also <a href="#showExtension">showExtension</a>(), <a href="#setOrientation">setOrientation</a>(), and <a href="#extension">extension</a>(). + +<h3 class=fn>void <a name="setModal"></a>QDialog::setModal ( bool modal ) +</h3><p>Sets whether <a href="#show">show</a>() should pop up the dialog as modal or modeless to <em>modal</em>. +See the <a href="qdialog.html#modal-prop">"modal"</a> property for details. +<h3 class=fn>void <a name="setOrientation"></a>QDialog::setOrientation ( <a href="qt.html#Orientation-enum">Orientation</a> orientation ) +</h3> +If <em>orientation</em> is <a href="qt.html#Orientation-enum">Horizontal</a>, the extension will be displayed +to the right of the dialog's main area. If <em>orientation</em> is <a href="qt.html#Orientation-enum">Vertical</a>, the extension will be displayed below the dialog's main +area. +<p> <p>See also <a href="#orientation">orientation</a>() and <a href="#setExtension">setExtension</a>(). + +<h3 class=fn>void <a name="setResult"></a>QDialog::setResult ( int i )<tt> [protected]</tt> +</h3> + +<p> Sets the modal dialog's result code to <em>i</em>. + +<h3 class=fn>void <a name="setSizeGripEnabled"></a>QDialog::setSizeGripEnabled ( bool ) +</h3><p>Sets whether the size grip is enabled. +See the <a href="qdialog.html#sizeGripEnabled-prop">"sizeGripEnabled"</a> property for details. +<h3 class=fn>void <a name="show"></a>QDialog::show ()<tt> [virtual]</tt> +</h3> +Shows the dialog as a <a href="#modeless">modeless</a> dialog. +Control returns immediately to the calling code. +<p> The dialog will be modal or modeless according to the value +of the <a href="#modal-prop">modal</a> property. +<p> <p>See also <a href="#exec">exec</a>() and <a href="#modal-prop">modal</a>. + +<p>Examples: <a href="movies-example.html#x494">movies/main.cpp</a>, <a href="regexptester-example.html#x2511">regexptester/main.cpp</a>, <a href="showimg-example.html#x1317">showimg/showimg.cpp</a>, and <a href="sql.html#x2220">sql/overview/form1/main.cpp</a>. +<p>Reimplemented from <a href="qwidget.html#show">QWidget</a>. +<h3 class=fn>void <a name="showExtension"></a>QDialog::showExtension ( bool showIt )<tt> [protected slot]</tt> +</h3> +If <em>showIt</em> is TRUE, the dialog's extension is shown; otherwise the +extension is hidden. +<p> This slot is usually connected to the <a href="qbutton.html#toggled">QButton::toggled</a>() signal +of a <a href="qpushbutton.html">QPushButton</a>. +<p> A dialog with a visible extension is not resizeable. +<p> <p>See also <a href="#show">show</a>(), <a href="#setExtension">setExtension</a>(), and <a href="#setOrientation">setOrientation</a>(). + +<hr><h2>Property Documentation</h2> +<h3 class=fn>bool <a name="modal-prop"></a>modal</h3> <p>This property holds whether <a href="#show">show</a>() should pop up the dialog as modal or modeless. +<p>By default, this property is false and show() pops up the dialog as +modeless. +<p> <a href="#exec">exec</a>() ignores the value of this property and always pops up the +dialog as modal. +<p> <p>See also <a href="#show">show</a>() and <a href="#exec">exec</a>(). + +<p>Set this property's value with <a href="#setModal">setModal</a>() and get this property's value with <a href="#isModal">isModal</a>(). +<h3 class=fn>bool <a name="sizeGripEnabled-prop"></a>sizeGripEnabled</h3> +<p>This property holds whether the size grip is enabled. +<p>A <a href="qsizegrip.html">QSizeGrip</a> is placed in the bottom right corner of the dialog when this +property is enabled. By default, the size grip is disabled. + +<p>Set this property's value with <a href="#setSizeGripEnabled">setSizeGripEnabled</a>() and get this property's value with <a href="#isSizeGripEnabled">isSizeGripEnabled</a>(). +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">Qt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |