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.
tqt3/examples/toplevel/toplevel.doc

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 retquire 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.
*/