CopperSpice API  1.8.2
Window and Dialog Widgets

A widget which does not have a parent widget is called a window. By default a window normally has a frame and a title bar however these can be omitted by enabling certain window flags. In GUI applications the window is where the user interface will be displayed.

Primary and Secondary Windows

Any QWidget with no parent is a window and will be listed in the desktop task bar. This is usually only desired for the main or primary window in the given GUI application.

A QWidget which does have a parent can still be a window by setting the Qt::WA_Window flag. These secondary windows are usually stacked on top of their parent window and do not have a desktop task bar entry of their own.

QMainWindow and QDialog

The QMainWindow and QDialog classes set the Qt::WA_Window flag in their respective constructors. These classes are designed to be used as a primary or secondary window and not as a child of some other window.

A main window can be used as the primary window for an application. The QMainWindow class has its own layout where a menu, toolbar, dockable widget, or a status bar can appear. The center area can be occupied by any kind of QWidget.

Dialog windows can be used as secondary windows to present the user with options and choices. Dialogs are created by inheriting from QDialog and using widgets and layouts to implement the user interface. In addition, CopperSpice provides a number of standard dialogs which can be used for common tasks like file or font selection.

Window Geometry

QWidget provides several methods which can adjust its geometry. Some of these methods operate on the client area alone while others include the window frame. This distinction only matters for decorated top level windows. For all child widgets, the frame geometry is equal to the widget's client geometry.

  • Including the window frame: x(), y(), frameGeometry(), pos(), and move()
  • Excluding the window frame: geometry(), width(), height(), rect(), and size()

This diagram shows what each method represents.

Geometry diagram

X11 Window Management

On X11 a window does not have a frame until the window manager, which is a separate Unix utility, decorates it. This happens asynchronously at some point after calling QWidget::show() or it may not happen at all. You can not make any assumptions about the decoration frame any particular window will receive.

A GUI program can not place windows on the screen. All a CopperSpice application can do is send a request to the window manager. This window manager is not required to comply with the GUI application. This means setting the location and size of a window is not guaranteed.