1 files changed, 132 insertions, 0 deletions
diff --git a/examples/toplevel/toplevel.doc b/examples/toplevel/toplevel.doc
new file mode 100644
index 000000000..0dd1a0d31
--- /dev/null
+++ b/examples/toplevel/toplevel.doc
@@ -0,0 +1,132 @@
+/*!   
+  \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. 
+*/