1
/****************************************************************************
3
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
** All rights reserved.
5
** Contact: Nokia Corporation (qt-info@nokia.com)
7
** This file is part of the documentation of the Qt Toolkit.
9
** $QT_BEGIN_LICENSE:LGPL$
10
** No Commercial Usage
11
** This file contains pre-release code and may not be distributed.
12
** You may use this file in accordance with the terms and conditions
13
** contained in the Technology Preview License Agreement accompanying
16
** GNU Lesser General Public License Usage
17
** Alternatively, this file may be used under the terms of the GNU Lesser
18
** General Public License version 2.1 as published by the Free Software
19
** Foundation and appearing in the file LICENSE.LGPL included in the
20
** packaging of this file. Please review the following information to
21
** ensure the GNU Lesser General Public License version 2.1 requirements
22
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24
** In addition, as a special exception, Nokia gives you certain additional
25
** rights. These rights are described in the Nokia Qt LGPL Exception
26
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28
** If you have questions regarding the use of this file, please contact
29
** Nokia at qt-info@nokia.com.
40
****************************************************************************/
44
\brief The QDesktopWidget class provides access to screen information on multi-head systems.
49
Systems with more than one graphics card and monitor can manage the
50
physical screen space available either as multiple desktops, or as a
51
large virtual desktop.
53
This class provides information about the user's desktop, such as its
54
total size, number of screens, the geometry of each screen, and whether
55
they are configured as separate desktops or a single virtual desktop.
57
Widgets provided by Qt use this class to place tooltips, menus and
58
dialog boxes on the correct screen for their parent or application
59
widgets. Applications can use this class to obtain information that
60
can be used to save window positions, or to place child widgets and
61
dialogs on one particular screen.
63
\section1 Obtaining a Desktop Widget
65
The QApplication::desktop() function is used to get an instance of
68
The widget's screenGeometry() function provides information about the
69
geometry of the available screens with. The number of screens
70
available is returned by screenCount, and the screenCountChanged()
71
signal is emitted when screens are added or removed.
72
The screen number that a particular point or widget is located in
73
is returned by screenNumber().
75
\section1 Screen Geometry
77
To obtain the dimensions of a particular screen, call the screenGeometry()
78
function. On some desktop environments, not all of the screen is
79
available for applications to use; for example, an application dock or
80
menu bar may take up some space. Use the availableGeometry() function
81
to obtain the available area for applications.
83
QDesktopWidget also inherits the QWidget properties, width() and
84
height(), which specify the size of the desktop. However, for
85
desktops with multiple screens, the size of the desktop is the union
86
of all the screen sizes, so width() and height() should \e not be
87
used for computing the size of a widget to be placed on one of the
90
On systems that are configured to use the available screens as a
91
single, large virtual desktop, the virtualDesktop property will be
92
set to true. In this case, the widget's size is usually the size of
93
the bounding rectangle of all the screens.
95
\section1 Use of the Primary Screen
97
For an application, the screen where the main widget resides is the
98
primary screen. This is stored in the primaryScreen property.
99
All windows opened in the context of the application should be
100
constrained to the boundaries of the primary screen; for example,
101
it would be inconvenient if a dialog box popped up on a different
102
screen, or split over two screens.
104
\image qdesktopwidget.png Managing Multiple Screens
106
In the illustration above, Application One's primary screen is
107
screen 0, and App Two's primary screen is screen 1.
109
\sa QApplication, QApplication::desktop(), QX11Info::appRootWindow()
113
\fn QDesktopWidget::QDesktopWidget()
117
Creates the desktop widget.
119
If the system supports a virtual desktop, this widget will have
120
the size of the virtual desktop; otherwise this widget will have
121
the size of the primary screen.
123
Instead of using QDesktopWidget directly, use QApplication::desktop().
127
\fn QDesktopWidget::~QDesktopWidget()
131
Destroys the desktop widget and frees any allocated resources.
135
\fn int QDesktopWidget::numScreens() const
137
Returns the number of available screens.
141
This function is deprecated. Use screenCount instead.
147
\fn QWidget *QDesktopWidget::screen(int screen)
149
Returns a widget that represents the screen with index \a screen
150
(a value of -1 means the default screen).
152
If the system uses a virtual desktop, the returned widget will
153
have the geometry of the entire virtual desktop; i.e., bounding
156
\sa primaryScreen, screenCount, virtualDesktop
160
\fn const QRect QDesktopWidget::availableGeometry(int screen) const
162
Returns the available geometry of the screen with index \a screen. What
163
is available will be subrect of screenGeometry() based on what the
164
platform decides is available (for example excludes the dock and menu bar
165
on Mac OS X, or the task bar on Windows). The default screen is used if
168
\sa screenNumber(), screenGeometry()
172
\fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const
175
Returns the available geometry of the screen which contains \a widget.
181
\fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const
184
Returns the available geometry of the screen which contains \a p.
191
\fn const QRect QDesktopWidget::screenGeometry(int screen) const
193
Returns the geometry of the screen with index \a screen. The default
194
screen is used if \a screen is -1.
200
\fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const
203
Returns the geometry of the screen which contains \a widget.
207
\fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const
210
Returns the geometry of the screen which contains \a p.
215
\fn int QDesktopWidget::screenNumber(const QWidget *widget) const
217
Returns the index of the screen that contains the largest
218
part of \a widget, or -1 if the widget not on a screen.
224
\fn int QDesktopWidget::screenNumber(const QPoint &point) const
227
Returns the index of the screen that contains the \a point, or the
228
screen which is the shortest distance from the \a point.
234
\fn void QDesktopWidget::resizeEvent(QResizeEvent *event)
239
\fn void QDesktopWidget::resized(int screen)
241
This signal is emitted when the size of \a screen changes.
245
\fn void QDesktopWidget::workAreaResized(int screen)
247
This signal is emitted when the work area available on \a screen changes.
251
\property QDesktopWidget::screenCount
252
\brief the number of screens currently available on the system.
256
\sa screenCountChanged()
260
\property QDesktopWidget::primaryScreen
261
\brief the index of the screen that is configured to be the primary screen
266
\property QDesktopWidget::virtualDesktop
268
\brief if the system manages the available screens in a virtual desktop.
270
For virtual desktops, screen() will always return the same widget.
271
The size of the virtual desktop is the size of this desktop
276
\fn void QDesktopWidget::screenCountChanged(int newCount)
280
This signal is emitted when the number of screens changes to \a newCount.