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