You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
133 lines
4.9 KiB
133 lines
4.9 KiB
/*!
|
|
\page toplevel-example.html
|
|
|
|
\ingroup examples
|
|
\title 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
|
|
\link designer-manual.book Qt Designer\endlink. The different
|
|
options are explained in the user interface through the use of
|
|
tooltips and What's This help. Load the \c options.ui file into
|
|
\link designer-manual.book Qt Designer\endlink for more details.
|
|
|
|
\quotefile toplevel/main.cpp
|
|
\printuntil }
|
|
|
|
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 \c options.ui.h
|
|
file.
|
|
|
|
\quotefile toplevel/options.ui.h
|
|
\printuntil WFlags
|
|
|
|
The \c apply() slot declares the widget flag variable \c f
|
|
and initializes it with the values
|
|
\list
|
|
\i \c WDestructiveClose - the widget will be automatically
|
|
destroyed when it is closed,
|
|
\i \c WType_TopLevel - the widget will be top level even if it
|
|
has a parent widget, and
|
|
\i \c WStyle_Customize - the flags override the default values
|
|
\endlist
|
|
Other flags are used depending on the options selected in the user
|
|
interface.
|
|
|
|
\printto bgTitle->isChecked()
|
|
The window gets a normal or dialog border depending on the selected
|
|
option.
|
|
|
|
\printto else
|
|
A titlebar with controls is provided if the appropriate options
|
|
have been checked.
|
|
|
|
\printto QWidget *parent
|
|
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.
|
|
|
|
\printto cbBehaviorStays
|
|
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 \c WGroupLeader flag to
|
|
prevent blocking through the modal main dialog. Applications
|
|
that can have multiple toplevel windows open simultaneously
|
|
should use this combination.
|
|
|
|
\printto cbBehaviorPopup
|
|
A toplevel widget can stay on top of the whole desktop if the
|
|
window manager supports this functionality.
|
|
\footnote Unfortunately some X11 window managers also require the \c
|
|
WX11BypassWM flag to be set in addition; but some other X11 window
|
|
managers will have problems if this flag is set. \endfootnote
|
|
|
|
Widgets that display important or realtime information (i.e. IRC
|
|
clients) might benefit from using that flag.
|
|
|
|
\printto cbBehaviorModal
|
|
A popup widget is a short lived modal widget that closes
|
|
automatically. Popup menus are a typical example for such widgets.
|
|
|
|
\printto cbBehaviorTool
|
|
A modal widget blocks input to other toplevel widgets, unless
|
|
those are in a different modal group (see \c 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.
|
|
|
|
\printto !widget
|
|
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.
|
|
|
|
\printto else
|
|
The widget is created if it has not been created yet, or if it was
|
|
closed (since we use the \c WDestructiveClose flag). Note that the
|
|
window is not visible yet.
|
|
\footnote The example uses QGuardedPtr to make sure that the
|
|
pointer is reset to zero when the widget object is destroyed
|
|
due to the \c WDestructiveClose flag. \endfootnote
|
|
|
|
\printto setCaption
|
|
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.
|
|
|
|
\printuntil 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.
|
|
|
|
\printuntil }
|
|
Finally the window is shown with the new attributes.
|
|
|
|
To build the example go to the toplevel directory
|
|
(\c QTDIR/examples/toplevel)
|
|
\footnote
|
|
We use \c QTDIR to stand for the directory where Qt is installed.
|
|
\endfootnote
|
|
and run \c qmake to generate the makefile, then use the make tool to
|
|
build the library.
|
|
*/
|