diff options
Diffstat (limited to 'doc/html/toplevel-example.html')
| -rw-r--r-- | doc/html/toplevel-example.html | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/doc/html/toplevel-example.html b/doc/html/toplevel-example.html new file mode 100644 index 0000000..d918275 --- /dev/null +++ b/doc/html/toplevel-example.html @@ -0,0 +1,239 @@ +<!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/examples/toplevel/toplevel.doc:1 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Toplevel Widgets</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>Toplevel Widgets</h1> + + + +<p> +This example demonstrates the use of Qt's widget flags to provide +toplevel widgets with customized window decorations. +<p> It provides a graphical user interface for selecting different +options for widget decoration and behavior, and passes the +appropriate widget flags to the <a href="qwidget.html">QWidget</a> constructor. +<a href="qwidget.html#reparent">QWidget::reparent</a>() is used to change the widget flags at runtime. +<p> <b>Warning:</b> Note that the interpretation and functionality of the +widget flags depends on the window manager used when running the +application. Many window managers do not support every possible flag +combination. +<p> The user interface providing the different options was created using +<a href="designer-manual.html">Qt Designer</a>. The different +options are explained in the user interface through the use of +tooltips and What's This help. Load the <tt>options.ui</tt> file into +<a href="designer-manual.html">Qt Designer</a> for more details. +<p> + +<pre> #include <<a href="qapplication-h.html">qapplication.h</a>> + #include "options.h" + + int main( int argc, char ** argv ) + { + <a href="qapplication.html">QApplication</a> a( argc, argv ); + OptionsDialog dlg; + return dlg.exec(); + } +</pre> +<p> The main function creates and displays the dialog for the user +interface. Note that this dialog is modal. +<p> The code relevant for this example is in the <tt>options.ui.h</tt> +file. +<p> + +<pre> void OptionsDialog::apply() + { + <a href="qstringlist.html">QStringList</a> flagList; + bool wstyle = false; + WFlags f = WDestructiveClose | WType_TopLevel | WStyle_Customize; +</pre> +<p> The <tt>apply()</tt> slot declares the <a href="qt.html#WidgetFlags">widget flag</a> variable <tt>f</tt> +and initializes it with the values +<ul> +<li> <tt>WDestructiveClose</tt> - the widget will be automatically +destroyed when it is closed, +<li> <tt>WType_TopLevel</tt> - the widget will be top level even if it +has a parent widget, and +<li> <tt>WStyle_Customize</tt> - the flags override the default values +</ul> +Other flags are used depending on the options selected in the user +interface. +<p> <pre> if ( bgBorder->isChecked() ) { + if ( rbBorderNormal->isChecked() ) { + f |= WStyle_NormalBorder; + flagList += "WStyle_NormalBorder"; + wstyle = true; + } + else if ( rbBorderDialog->isChecked() ) { + f |= WStyle_DialogBorder; + flagList += "WStyle_DialogBorder"; + wstyle = true; + } +</pre>The window gets a normal or dialog border depending on the selected +option. +<p> <pre> if ( bgTitle->isChecked() ) { + f |= WStyle_Title; + flagList += "WStyle_Title"; + wstyle = true; + if ( cbTitleSystem->isChecked() ) { + f |= WStyle_SysMenu; + flagList += "WStyle_SysMenu"; + } + if ( cbTitleMinimize->isChecked() ) { + f |= WStyle_Minimize; + flagList += "WStyle_Minimize"; + } + if ( cbTitleMaximize->isChecked() ) { + f |= WStyle_Maximize; + flagList += "WStyle_Maximize"; + } + if ( cbTitleContext->isChecked() ) { + f |= WStyle_ContextHelp; + flagList += "WStyle_ContextHelp"; + } + } +</pre>A titlebar with controls is provided if the appropriate options +have been checked. +<p> <pre> } else { + f |= WStyle_NoBorder; + flagList += "WStyle_NoBorder"; + wstyle = true; + } +</pre>If the window should not have a border it cannot have a titlebar. +Widgets that provide their own (e.g. themed) window decoration +should use this flag. +<p> <pre> <a href="qwidget.html">QWidget</a> *parent = this; + if ( cbBehaviorTaskbar->isChecked() ) { + parent = 0; + f |= WGroupLeader; + flagList += "WGroupLeader"; + } +</pre>If a toplevel widget has a parent it will not have a taskbar +entry, and on most window managers it will always stay on +top of the parent widget. This is the standard behavior for +dialog boxes, especially if they are modeless, and for other +secondary toplevel widgets. +<p> To provide a taskbar entry the widget must have no parent, +in which case we need to use the <tt>WGroupLeader</tt> flag to +prevent blocking through the modal main dialog. Applications +that can have multiple toplevel windows open simultaneously +should use this combination. +<p> <pre> if ( cbBehaviorStays->isChecked() ) { + f |= WStyle_StaysOnTop /*| WX11BypassWM*/; + flagList += "WStyle_StaysOnTop"; + wstyle = true; + } +</pre>A toplevel widget can stay on top of the whole desktop if the +window manager supports this functionality. +<a href="#footnote1"><sup>(1)</sup></a><a name="footnote-call1"></a> +<p> Widgets that display important or realtime information (i.e. IRC +clients) might benefit from using that flag. +<p> <pre> if ( cbBehaviorPopup->isChecked() ) { + f |= WType_Popup; + flagList += "WType_Popup"; + } +</pre>A popup widget is a short lived modal widget that closes +automatically. Popup menus are a typical example for such widgets. +<p> <pre> if ( cbBehaviorModal->isChecked() ) { + f |= WShowModal; + flagList += "WShowModal"; + } +</pre>A modal widget blocks input to other toplevel widgets, unless +those are in a different modal group (see <tt>WGroupLeader</tt>). +Dialogs are often modal, and the <a href="qdialog.html">QDialog</a> class provides an easy API +to create and display them without the need to explicitly use this +flag. +<p> <pre> if ( cbBehaviorTool->isChecked() ) { + f |= WStyle_Tool; + flagList += "WStyle_Tool"; + wstyle = true; + } + + if (wstyle) + <a name="x2534"></a> flagList.<a href="qvaluelist.html#push_front">push_front</a>("WStyle_Customize"); +</pre>A tool window will never have a task bar entry (even if it +has no parent widget), and often has a smaller window +decoration. Tool windows are frequently used instead of +modeless dialogs. +<p> <pre> if ( !widget ) { + widget = new <a href="qvbox.html">QVBox</a>( parent, 0, f ); + <a name="x2530"></a> widget-><a href="qframe.html#setMargin">setMargin</a>( 20 ); + <a name="x2533"></a> <a href="qlabel.html">QLabel</a> *label = new <a href="qlabel.html">QLabel</a>(flagList.<a href="qstringlist.html#join">join</a>("&nbsp;| "), widget); + <a name="x2532"></a> label-><a href="qlabel.html#setTextFormat">setTextFormat</a>(RichText); + <a name="x2531"></a> label-><a href="qlabel.html#setAlignment">setAlignment</a>(WordBreak); + <a href="qpushbutton.html">QPushButton</a> *okButton = new <a href="qpushbutton.html">QPushButton</a>( "Close", widget ); + <a name="x2535"></a> connect( okButton, SIGNAL(<a href="qbutton.html#clicked">clicked</a>()), widget, SLOT(<a href="qwidget.html#close">close</a>()) ); + <a name="x2537"></a> widget-><a href="qwidget.html#move">move</a>( pos() ); +</pre>The widget is created if it has not been created yet, or if it was +closed (since we use the <tt>WDestructiveClose</tt> flag). Note that the +window is not visible yet. +<a href="#footnote2"><sup>(2)</sup></a><a name="footnote-call2"></a> +<p> <pre> } else { + <a name="x2538"></a><a name="x2536"></a> widget-><a href="qwidget.html#reparent">reparent</a>( parent, f, widget-><a href="qwidget.html#geometry">geometry</a>().topLeft(), FALSE); + } +</pre>If the widget has already been created the reparent() function is +used to modify the widget's flags. The widget's geometry is not +changed, and the window is not shown again. +<p> <pre> <a name="x2539"></a> widget-><a href="qwidget.html#setCaption">setCaption</a>( leCaption->text() ); + <a name="x2540"></a> widget-><a href="qwidget.html#setIcon">setIcon</a>( leIcon->text() ); + <a name="x2541"></a> widget-><a href="qwidget.html#setWindowOpacity">setWindowOpacity</a>(double(slTransparency->maxValue() - slTransparency->value()) / 100); + + <a name="x2542"></a> widget-><a href="qwidget.html#show">show</a>(); +</pre>Finally the higher level properties such as the window's caption and +icon are set. The window transparency is set according to the slider +value. Note that this will only have effect on systems that support +this attribute for toplevel window. +<p> <pre> } +</pre>Finally the window is shown with the new attributes. +<p> To build the example go to the toplevel directory +(<tt>QTDIR/examples/toplevel</tt>) +<a href="#footnote3"><sup>(3)</sup></a><a name="footnote-call3"></a> +and run <tt>qmake</tt> to generate the makefile, then use the make tool to +build the library. + +<hr> +<ol> <li><a name="footnote1"></a> +Unfortunately some X11 window managers also require the <tt>WX11BypassWM</tt> flag to be set in addition; but some other X11 window +managers will have problems if this flag is set. <a href="#footnote-call1">Back...</a> <li><a name="footnote2"></a> +The example uses <a href="qguardedptr.html">QGuardedPtr</a> to make sure that the +pointer is reset to zero when the widget object is destroyed +due to the <tt>WDestructiveClose</tt> flag. <a href="#footnote-call2">Back...</a> <li><a name="footnote3"></a> + +We use <tt>QTDIR</tt> to stand for the directory where Qt is installed. + <a href="#footnote-call3">Back...</a></ol> +</hr><p>See also <a href="examples.html">Examples</a>. + +<!-- eof --> +<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> |