Toplevel Widgets

This example demonstrates the use of Qt's widget flags to provide toplevel widgets with customized window decorations.

It provides a graphical user interface for selecting different options for widget decoration and behavior, and passes the appropriate widget flags to the QWidget constructor. QWidget::reparent() is used to change the widget flags at runtime.

Warning: 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.

The user interface providing the different options was created using Qt Designer. The different options are explained in the user interface through the use of tooltips and What's This help. Load the options.ui file into Qt Designer for more details.

    #include <qapplication.h>
    #include "options.h"

    int main( int argc, char ** argv )
    {
        QApplication a( argc, argv );
        OptionsDialog dlg;
        return dlg.exec();
    }

The main function creates and displays the dialog for the user interface. Note that this dialog is modal.

The code relevant for this example is in the options.ui.h file.

    void OptionsDialog::apply()
    {
        QStringList flagList;
        bool wstyle = false;
        WFlags f = WDestructiveClose | WType_TopLevel | WStyle_Customize;

The apply() slot declares the widget flag variable f and initializes it with the values

WDestructiveClose - the widget will be automatically destroyed when it is closed,
WType_TopLevel - the widget will be top level even if it has a parent widget, and
WStyle_Customize - the flags override the default values

Other flags are used depending on the options selected in the user interface.

        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;
            }

The window gets a normal or dialog border depending on the selected option.

            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";
                }
            }

A titlebar with controls is provided if the appropriate options have been checked.

        } else {
            f |= WStyle_NoBorder;
            flagList += "WStyle_NoBorder";
            wstyle = true;
        }

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.

        QWidget *parent = this;
        if ( cbBehaviorTaskbar->isChecked() ) {
            parent = 0;
            f |= WGroupLeader;
            flagList += "WGroupLeader";
        }

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.

To provide a taskbar entry the widget must have no parent, in which case we need to use the WGroupLeader flag to prevent blocking through the modal main dialog. Applications that can have multiple toplevel windows open simultaneously should use this combination.

        if ( cbBehaviorStays->isChecked() ) {
            f |= WStyle_StaysOnTop /*| WX11BypassWM*/;
            flagList += "WStyle_StaysOnTop";
            wstyle = true;
        }

A toplevel widget can stay on top of the whole desktop if the window manager supports this functionality. ⁽¹⁾

Widgets that display important or realtime information (i.e. IRC clients) might benefit from using that flag.

        if ( cbBehaviorPopup->isChecked() ) {
            f |= WType_Popup;
            flagList += "WType_Popup";
        }

A popup widget is a short lived modal widget that closes automatically. Popup menus are a typical example for such widgets.

        if ( cbBehaviorModal->isChecked() ) {
            f |= WShowModal;
            flagList += "WShowModal";
        }

A modal widget blocks input to other toplevel widgets, unless those are in a different modal group (see WGroupLeader). Dialogs are often modal, and the QDialog class provides an easy API to create and display them without the need to explicitly use this flag.

        if ( cbBehaviorTool->isChecked() ) {
            f |= WStyle_Tool;
            flagList += "WStyle_Tool";
            wstyle = true;
        }

        if (wstyle)
            flagList.push_front("WStyle_Customize");

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.

        if ( !widget ) {
            widget = new QVBox( parent, 0, f );
            widget->setMargin( 20 );
            QLabel *label = new QLabel(flagList.join("&nbsp;| "), widget);
            label->setTextFormat(RichText);
            label->setAlignment(WordBreak);
            QPushButton *okButton = new QPushButton( "Close", widget );
            connect( okButton, SIGNAL(clicked()), widget, SLOT(close()) );
            widget->move( pos() );

The widget is created if it has not been created yet, or if it was closed (since we use the WDestructiveClose flag). Note that the window is not visible yet. ⁽²⁾

        } else {
            widget->reparent( parent, f, widget->geometry().topLeft(), FALSE);
        }

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.

        widget->setCaption( leCaption->text() );
        widget->setIcon( leIcon->text() );
        widget->setWindowOpacity(double(slTransparency->maxValue() - slTransparency->value()) / 100);

        widget->show();

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.

Finally the window is shown with the new attributes.

To build the example go to the toplevel directory (QTDIR/examples/toplevel) ⁽³⁾ and run qmake to generate the makefile, then use the make tool to build the library.

Unfortunately some X11 window managers also require the WX11BypassWM flag to be set in addition; but some other X11 window managers will have problems if this flag is set. Back...
The example uses QGuardedPtr to make sure that the pointer is reset to zero when the widget object is destroyed due to the WDestructiveClose flag. Back...
We use QTDIR to stand for the directory where Qt is installed. Back...