1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \class QDesktopWidget
30    \brief The QDesktopWidget class provides access to screen information on multi-head systems.
31
32    \ingroup advanced
33    \ingroup desktop
34    \inmodule QtWidgets
35    \obsolete
36
37    Systems with more than one graphics card and monitor can manage the
38    physical screen space available either as multiple desktops, or as a
39    large virtual desktop.
40
41    This class provides information about the user's desktop, such as its
42    total size, number of screens, the geometry of each screen, and whether
43    they are configured as separate desktops or a single virtual desktop.
44
45    Widgets provided by Qt use this class to place tooltips, menus and
46    dialog boxes on the correct screen for their parent or application
47    widgets. Applications can use this class to obtain information that
48    can be used to save window positions, or to place child widgets and
49    dialogs on one particular screen.
50
51    \section1 Obtaining a Desktop Widget
52
53    The QApplication::desktop() function is used to get an instance of
54    QDesktopWidget.
55
56    The widget's screenGeometry() function provides information about the
57    geometry of the available screens with. The number of screens
58    available is returned by screenCount, and the screenCountChanged()
59    signal is emitted when screens are added or removed.
60    The screen number that a particular point or widget is located in
61    is returned by screenNumber().
62
63    \section1 Screen Geometry
64
65    To obtain the dimensions of a particular screen, call the screenGeometry()
66    function. On some desktop environments, not all of the screen is
67    available for applications to use; for example, an application dock or
68    menu bar may take up some space. Use the availableGeometry() function
69    to obtain the available area for applications.
70
71    QDesktopWidget also inherits the QWidget properties, width() and
72    height(), which specify the size of the desktop. However, for
73    desktops with multiple screens, the size of the desktop is the union
74    of all the screen sizes, so width() and height() should \e not be
75    used for computing the size of a widget to be placed on one of the
76    screens.
77
78    On systems that are configured to use the available screens as a
79    single, large virtual desktop, the virtualDesktop property will be
80    set to true. In this case, the widget's size is usually the size of
81    the bounding rectangle of all the screens.
82
83    \section1 Use of the Primary Screen
84
85    For an application, the screen where the main widget resides is the
86    primary screen. This is stored in the primaryScreen property.
87    All windows opened in the context of the application should be
88    constrained to the boundaries of the primary screen; for example,
89    it would be inconvenient if a dialog box popped up on a different
90    screen, or split over two screens.
91
92    \image qdesktopwidget.png Managing Multiple Screens
93
94    In the illustration above, Application One's primary screen is
95    screen 0, and App Two's primary screen is screen 1.
96
97    \sa QApplication, QApplication::desktop()
98*/
99
100/*!
101    \fn QDesktopWidget::QDesktopWidget()
102
103    \internal
104
105    Creates the desktop widget.
106
107    If the system supports a virtual desktop, this widget will have
108    the size of the virtual desktop; otherwise this widget will have
109    the size of the primary screen.
110
111    Instead of using QDesktopWidget directly, use QApplication::desktop().
112*/
113
114/*!
115    \fn QDesktopWidget::~QDesktopWidget()
116
117    \internal
118
119    Destroys the desktop widget and frees any allocated resources.
120*/
121
122/*!
123    \fn int QDesktopWidget::numScreens() const
124
125    Returns the number of available screens.
126
127    \obsolete
128
129    Use QGuiApplication::screens() instead.
130
131    \sa primaryScreen
132*/
133
134/*!
135    \fn QWidget *QDesktopWidget::screen(int screen)
136
137    Returns a widget that represents the screen with index \a screen
138    (a value of -1 means the default screen).
139
140    If the system uses a virtual desktop, the returned widget will
141    have the geometry of the entire virtual desktop; i.e., bounding
142    every \a screen.
143
144    \obsolete
145
146    Use QScreen instead.
147
148    \sa primaryScreen, screenCount, virtualDesktop
149*/
150
151/*!
152    \fn const QRect QDesktopWidget::availableGeometry(int screen) const
153
154     Returns the available geometry of the screen with index \a screen. What
155     is available will be subrect of screenGeometry() based on what the
156     platform decides is available (for example excludes the dock and menu bar
157     on \macos, or the task bar on Windows). The default screen is used if
158     \a screen is -1.
159
160    \obsolete
161
162    Use QGuiApplication::screens() instead.
163
164     \sa screenNumber(), screenGeometry(), QScreen::availableGeometry()
165*/
166
167/*!
168    \fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const
169    \overload
170
171    Returns the available geometry of the screen which contains \a widget.
172
173    \sa screenGeometry()
174*/
175
176/*!
177    \fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const
178    \overload
179
180    Returns the available geometry of the screen which contains \a p.
181
182    \obsolete
183
184    Use QGuiApplication::screenAt() instead.
185
186    \sa screenGeometry()
187*/
188
189
190/*!
191    \fn const QRect QDesktopWidget::screenGeometry(int screen) const
192
193    Returns the geometry of the screen with index \a screen. The default
194    screen is used if \a screen is -1.
195
196    \obsolete
197
198    Use QGuiApplication::screens() instead.
199
200    \sa screenNumber()
201*/
202
203/*!
204    \fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const
205    \overload
206
207    Returns the geometry of the screen which contains \a widget.
208*/
209
210/*!
211    \fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const
212    \overload
213
214    Returns the geometry of the screen which contains \a p.
215
216    \obsolete
217
218    Use QGuiApplication::screenAt() instead.
219*/
220
221
222/*!
223    \fn int QDesktopWidget::screenNumber(const QWidget *widget) const
224
225    Returns the index of the screen that contains the largest
226    part of \a widget, or -1 if the widget not on a screen.
227
228    \sa primaryScreen
229*/
230
231/*!
232    \fn int QDesktopWidget::screenNumber(const QPoint &point) const
233
234    \overload
235    Returns the index of the screen that contains the \a point, or the
236    screen which is the shortest distance from the \a point.
237
238    \obsolete
239
240    Use QGuiApplication::screenAt() instead.
241
242    \sa primaryScreen
243*/
244
245/*!
246    \fn void QDesktopWidget::resizeEvent(QResizeEvent *event)
247    \reimp
248    \internal
249*/
250
251/*!
252    \fn void QDesktopWidget::resized(int screen)
253
254    This signal is emitted when the size of \a screen changes.
255
256    \obsolete
257
258    Use QScreen::geometryChanged() instead.
259*/
260
261/*!
262    \fn void QDesktopWidget::workAreaResized(int screen)
263
264    This signal is emitted when the work area available on \a screen changes.
265
266    \obsolete
267
268    Use QScreen::availableGeometryChanged() instead.
269*/
270
271/*!
272    \property QDesktopWidget::screenCount
273    \brief the number of screens currently available on the system.
274
275    \obsolete
276
277    Use QGuiApplication::screens() instead.
278
279    \since 4.6
280*/
281
282/*!
283    \property QDesktopWidget::primaryScreen
284    \brief the index of the screen that is configured to be the primary screen
285    on the system.
286
287    \obsolete
288
289    Use QGuiApplication::primaryScreen() instead.
290*/
291
292/*!
293    \property QDesktopWidget::virtualDesktop
294
295    \brief if the system manages the available screens in a virtual desktop.
296
297    For virtual desktops, screen() will always return the same widget.
298    The size of the virtual desktop is the size of this desktop
299    widget.
300
301    \obsolete
302
303    Use QScreen::virtualSiblings() of primary screen instead.
304*/
305
306/*!
307    \fn void QDesktopWidget::screenCountChanged(int newCount)
308
309    \since 4.6
310
311    This signal is emitted when the number of screens changes to \a newCount.
312
313    \obsolete
314
315    Use QGuiApplication::screenAdded and QGuiApplication::screenRemoved() instead.
316
317    \sa screenCount
318*/
319
320
321/*!
322    \fn void QDesktopWidget::primaryScreenChanged()
323
324    \since 5.6
325
326    \brief This signal is emitted whenever the primary screen changes.
327
328    \note This doesn't mean the QDesktopWidget::primaryScreen index will
329    necessarily be different, but now it will refer to the new primary screen.
330
331    \obsolete
332
333    Use QGuiApplication::primaryScreenChanged() instead.
334
335    \sa primaryScreen, screenGeometry()
336*/
337