CopperSpice API  1.7.2
Widget Application Window and Dialog Widgets

A widget which is not embedded in a parent widget is called a window. Usually, windows have a frame and a title bar, although it is also possible to create windows without such decoration using suitable window flags. Windowpane and the various subclasses of QDialog are the most common window types.

In applications, windows provide the screen space upon which the user interface is built. Windows separate applications visually from each other and usually provide a window decoration that allows the user to resize and position the applications according to his preferences. Windows are typically integrated into the desktop environment and to some degree managed by the window management system that the desktop environment provides. For instance, selected windows of an application are represented in the task bar.

Primary and Secondary Windows

Any QWidget that has no parent will become a window and will on most platforms be listed in the desktop's task bar. This is usually only wanted for one window in the application, the primary window.

In addition, a QWidget that has a parent can become a window by setting the Qt::WA_Window flag. Depending on the window management system such secondary windows are usually stacked on top of their respective parent window, and not have a task bar entry of their own.

The QMainWindow and the QDialog classes set the Qt::WA_Window flag in their constructor, as they are designed to be used as windows and provide facilities that are not wanted for child widgets.

Main Windows and Dialogs

The Application Main Window provides the foundation for building the application's main user interface and is created by subclassing QMainWindow. QMainWindow has its own layout to which you can add a menu bar, tool bars, dockable widgets and a status bar. The center area can be occupied by any kind of QWidget.

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

Both main windows and dialogs can be created with the Designer application, the CopperSpice visual design tool. Using the Designer application is a faster than hand coding and makes it easy to test different design ideas.

Window Geometry

QWidget provides several functions that deal with a widget's geometry. Some of these functions operate on the pure client area (i.e. the window excluding the window frame), others include the window frame. The differentiation is done in a way that covers the most common usage transparently.

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

Note that the distinction only matters for decorated top-level widgets. For all child widgets, the frame geometry is equal to the widget's client geometry.

This diagram shows most of the functions in use:

X11 Peculiarities

On X11, a window does not have a frame until the window manager decorates it. This happens asynchronously at some point in time after calling QWidget::show() and the first paint event the window receives, or it does not happen at all. Bear in mind that X11 is policy-free (others call it flexible). Thus you can not make any safe assumption about the decoration frame your window will get. Basic rule: There's always one user who uses a window manager that breaks your assumption, and who will complain to you.

A toolkit can not simply place windows on the screen. All CopperSpice can do is send certain hints to the window manager. The window manager, a separate process, may either obey, ignore, or misunderstand them. Due to the partially unclear Inter-Client Communication Conventions Manual (ICCCM), window placement is handled quite differently in existing window managers.

X11 provides no standard or easy way to get the frame geometry once the window is decorated. CopperSpice solves this problem with nifty heuristics and clever code that works on a wide range of window managers that exist today. Do not be surprised if you find one where QWidget::frameGeometry() returns wrong results though.

Nor does X11 provide a way to maximize a window. QWidget::showMaximized() has to emulate the feature. Its result depends on the result of QWidget::frameGeometry() and the capability of the window manager to do proper window placement, neither of which can be guaranteed.