/usr/share/qt3/doc/html/toplevel-example.html

<!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&nbsp;Classes</font></a>
 | <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
 | <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
 | <a href="groups.html">
<font color="#004faf">Grouped&nbsp;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 &lt;<a href="qapplication-h.html">qapplication.h</a>&gt;
    #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-&gt;isChecked() ) {
            if ( rbBorderNormal-&gt;isChecked() ) {
                f |= WStyle_NormalBorder;
                flagList += "WStyle_NormalBorder";
                wstyle = true;
            }
            else if ( rbBorderDialog-&gt;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-&gt;isChecked() ) {
                f |= WStyle_Title;
                flagList += "WStyle_Title";
                wstyle = true;
                if ( cbTitleSystem-&gt;isChecked() ) {
                    f |= WStyle_SysMenu;
                    flagList += "WStyle_SysMenu";
                }
                if ( cbTitleMinimize-&gt;isChecked() ) {
                    f |= WStyle_Minimize;
                    flagList += "WStyle_Minimize";
                }
                if ( cbTitleMaximize-&gt;isChecked() ) {
                    f |= WStyle_Maximize;
                    flagList += "WStyle_Maximize";
                }
                if ( cbTitleContext-&gt;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-&gt;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-&gt;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-&gt;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-&gt;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-&gt;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-&gt;<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>("&amp;nbsp;| "), widget);
    <a name="x2532"></a>        label-&gt;<a href="qlabel.html#setTextFormat">setTextFormat</a>(RichText);
    <a name="x2531"></a>        label-&gt;<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-&gt;<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-&gt;<a href="qwidget.html#reparent">reparent</a>( parent, f, widget-&gt;<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-&gt;<a href="qwidget.html#setCaption">setCaption</a>( leCaption-&gt;text() );
    <a name="x2540"></a>    widget-&gt;<a href="qwidget.html#setIcon">setIcon</a>( leIcon-&gt;text() );
    <a name="x2541"></a>    widget-&gt;<a href="qwidget.html#setWindowOpacity">setWindowOpacity</a>(double(slTransparency-&gt;maxValue() - slTransparency-&gt;value()) / 100);

    <a name="x2542"></a>    widget-&gt;<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 &copy; 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>
qt3-doc 3:3.3.8-b-8ubuntu3 / usr / share / qt3 / doc / html / toplevel-example.html
