/*!   
  \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. 
*/