From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/toplevel-example.html | 239 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 doc/html/toplevel-example.html (limited to 'doc/html/toplevel-example.html') 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 @@ + + + + + +Toplevel Widgets + + + + + + + +

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