CopperSpice API  1.9.1
QPlatformWindow Class Reference

Provides an abstraction for top level windows. More...

Inheritance diagram for QPlatformWindow:

Public Methods

 QPlatformWindow (QWindow *window)
virtual ~QPlatformWindow ()
virtual qreal devicePixelRatio () const
QSurfaceFormat format () const override
virtual QMargins frameMargins () const
virtual bool frameStrutEventsEnabled () const
virtual QRect geometry () const
virtual void handleContentOrientationChange (Qt::ScreenOrientation orientation)
virtual void invalidateSurface ()
virtual bool isActive () const
virtual bool isAlertState () const
virtual bool isEmbedded (const QPlatformWindow *parentWindow=nullptr) const
virtual bool isExposed () const
virtual void lower ()
virtual QPoint mapFromGlobal (const QPoint &pos) const
virtual QPoint mapToGlobal (const QPoint &pos) const
virtual QRect normalGeometry () const
QPlatformWindow * parent () const
virtual void propagateSizeHints ()
virtual void raise ()
virtual void requestActivateWindow ()
virtual void requestUpdate ()
QPlatformScreenscreen () const
virtual void setAlertState (bool enabled)
virtual void setFrameStrutEventsEnabled (bool enabled)
virtual void setGeometry (const QRect &rect)
virtual bool setKeyboardGrabEnabled (bool grab)
virtual void setMask (const QRegion &region)
virtual bool setMouseGrabEnabled (bool grab)
virtual void setOpacity (qreal level)
virtual void setParent (const QPlatformWindow *parent)
virtual void setVisible (bool visible)
virtual void setWindowFilePath (const QString &filePath)
virtual void setWindowFlags (Qt::WindowFlags flags)
virtual void setWindowIcon (const QIcon &icon)
virtual bool setWindowModified (bool modified)
virtual void setWindowState (Qt::WindowState state)
virtual void setWindowTitle (const QString &title)
virtual bool startSystemResize (const QPoint &pos, Qt::Corner corner)
QWindowwindow () const
QSize windowBaseSize () const
QRectF windowClosestAcceptableGeometry (const QRectF &nativeRect) const
virtual void windowEvent (QEvent *event)
QRect windowFrameGeometry () const
QRect windowGeometry () const
QSize windowMaximumSize () const
QSize windowMinimumSize () const
QSize windowSizeIncrement () const
virtual WId winId () const

Static Public Methods

static QRectF closestAcceptableGeometry (const QWindow *window, const QRectF &nativeRect)
static QRect initialGeometry (const QWindow *window, const QRect &initialGeometry, int defaultWidth, int defaultHeight)

Protected Methods

QPlatformScreenscreenForGeometry (const QRect &newGeometry) const

Static Protected Methods

static QSize constrainWindowSize (const QSize &size)
static QString formatWindowTitle (const QString &title, const QString &separator)

Detailed Description

The QPlatformWindow abstraction is used by QWindow for all top level windows. A platform window is created by calling the createPlatformWindow() method in QPlatformIntegration. QPlatformWindow represents the frame of a window. It does not address how the contents of the window are rendered.

Visible QWindows will always have a corresponding QPlatformWindow. It is not necessary for all windows to have a QBackingStore. QPlatformWindow is the way the platform system defines how native child windows should be supported. The platform specific window handle can be retrieved by calling the winId() method.

Implementation Details

Mouse grab
CopperSpice expects windows to automatically grab the mouse if the user presses a button until the button is released. Automatic grab should be released if some window is explicitly grabbed.
Enter/Leave events

If there is a window explicitly grabbing mouse events setMouseGrabEnabled(), enter and leave events should only be sent to the grabbing window when mouse cursor passes over the grabbing window boundary. Other windows will not receive enter or leave events while the grab is active. While an automatic mouse grab caused by a mouse button press is active, no window will receive enter or leave events. When the last mouse button is released, the autograbbing window will receive leave event if mouse cursor is no longer within the window boundary.

When any grab starts the window under cursor will receive a leave event unless it is the grabbing window.

When any grab ends the window under cursor will receive an enter event unless it was the grabbing window.

Window positioning
When calling QWindow::setFramePosition(), the flag QWindowPrivate::positionPolicy is set to QWindowPrivate::WindowFrameInclusive. This means the position includes the window frame, whose size is at this point unknown and the geometry's topleft point is the position of the window frame.
See also
QBackingStore, QWindow

Constructor & Destructor Documentation

QPlatformWindow::QPlatformWindow ( QWindow window)

Constructs a platform window with the given top level window.

QPlatformWindow::~QPlatformWindow ( )

Virtual destructor does not delete the top level window.

Method Documentation

QRectF QPlatformWindow::closestAcceptableGeometry ( const QWindow window,
const QRectF nativeRect 

Returns the closest acceptable geometry for a given window before a resize or move event is handled. This is used to implement heightForWidth().

QSize QPlatformWindow::constrainWindowSize ( const QSize size)

Returns size with both dimensions bounded to [0, QWINDOWSIZE_MAX].

qreal QPlatformWindow::devicePixelRatio ( ) const

Reimplement in subclasses to return the device pixel ratio for the window. This is the ratio between physical pixels and device-independent pixels.

See also
QSurfaceFormat QPlatformWindow::format ( ) const

Returns the actual surface format of the window.

Implements QPlatformSurface

QString QPlatformWindow::formatWindowTitle ( const QString title,
const QString separator 

Call this method to put together a window title composed of a title and a separator for the application display name. If the display name is not set and the title is empty, the raw application name is used.

QMargins QPlatformWindow::frameMargins ( ) const

Additional documentation pending.

bool QPlatformWindow::frameStrutEventsEnabled ( ) const

Reimplement this method to return whether frame strut events are enabled.

QRect QPlatformWindow::geometry ( ) const

Returns the current geometry of a window.

void QPlatformWindow::handleContentOrientationChange ( Qt::ScreenOrientation  orientation)

Handle changes to the orientation of the platform window's contents. This is a hint to the window manager in case it needs to display additional content like popups, dialogs, status bars, or similar in relation to the window.

See also
QRect QPlatformWindow::initialGeometry ( const QWindow window,
const QRect initialGeometry,
int  defaultWidth,
int  defaultHeight 

Helper function to get initial geometry on windowing systems which do not do smart positioning and also do not provide a means of centering a transient window w.r.t. its parent. For example this is useful on Windows and Mac OS but not X11, because an X11 window manager typically tries to layout new windows to optimize usage of the available desktop space. However if the given window already has geometry which the application has initialized, it takes priority.

void QPlatformWindow::invalidateSurface ( )

Invalidates the window's surface by releasing its surface buffers. Many platforms do not support releasing the surface memory, and the default implementation does nothing. The platform window is expected to recreate the surface again if it is needed. For instance, if an OpenGL context is made current on this window.

bool QPlatformWindow::isActive ( ) const

Returns true if the window should be drawn as the active window.

bool QPlatformWindow::isAlertState ( ) const

Additional documentation pending.

bool QPlatformWindow::isEmbedded ( const QPlatformWindow *  parentWindow = nullptr) const

Returns true if the window is a descendant of an embedded non CopperSpice window. An example of an embedded non CopperSpice window is the parent window of an in process QAxServer. If parentWindow is not a nullptr the method only checks if the window is embedded in the specified parentWindow.

bool QPlatformWindow::isExposed ( ) const

Returns true if this window is exposed in the windowing system. An exposeEvent() is sent every time this value changes.

void QPlatformWindow::lower ( )

Reimplement if the platform supports reordering windows.

QPoint QPlatformWindow::mapFromGlobal ( const QPoint pos) const

Translates the global screen coordinate pos to window coordinates using native methods. This is required for embedded windows, where the topmost QWindow coordinates are not global screen coordinates. Returns the value of pos if there is no platform specific implementation.

QPoint QPlatformWindow::mapToGlobal ( const QPoint pos) const

Translates the window coordinate pos to global screen coordinates using native methods. This is required for embedded windows, where the topmost QWindow coordinates are not global screen coordinates. Returns the value of pos if there is no platform specific implementation.

QRect QPlatformWindow::normalGeometry ( ) const

Returns the geometry of a window in 'normal' state (neither maximized, fullscreen nor minimized) for saving geometries to application settings.

QPlatformWindow * QPlatformWindow::parent ( ) const

Returns the parent platform window or a nullptr if it is an orphan.

void QPlatformWindow::propagateSizeHints ( )

Reimplement to propagate the size hints of the QWindow. The size hints include QWindow::minimumSize(), QWindow::maximumSize(), QWindow::sizeIncrement(), QWindow::baseSize()

void QPlatformWindow::raise ( )

Reimplement to support raising windows to the top of the desktop.

void QPlatformWindow::requestActivateWindow ( )

Reimplement to request activation focus for a window. Some window systems will probably not have callbacks for this functionality, and then calling QWindowSystemInterface::handleWindowActivated() would be sufficient. If the window system has some event handling/callbacks then call QWindowSystemInterface::handleWindowActivated() when the window system gives the notification.

Default implementation calls QWindowSystem::handleWindowActivated()

void QPlatformWindow::requestUpdate ( )

Requests a QEvent::UpdateRequest event. The event will be delivered to the corresponding QWindow.

QPlatformWindow subclasses can override this method to provide display refresh synchronized updates. The event should be delivered using QWindowPrivate::deliverUpdateRequest() to stay in sync with the internal state of the QWindow. The default implementation posts an UpdateRequest event to the window after 5 ms. The additional time is there to give the event loop a bit of idle time to gather system events.

QPlatformScreen * QPlatformWindow::screen ( ) const

Returns the platform screen handle corresponding to this platform window or nullptr if the window is not associated with a screen.

QPlatformScreen * QPlatformWindow::screenForGeometry ( const QRect newGeometry) const

Helper method determines the new screen for newGeometry in response to a geometry changed event. Returns the new screen if the window was moved to another virtual sibling. If the screen changes, the platform plugin should call QWindowSystemInterface::handleWindowScreenChanged().

The current screen will always be returned for child windows since they should never signal screen changes.

void QPlatformWindow::setAlertState ( bool  enabled)

Reimplement this method to set whether the window demands attention (for example, by flashing the taskbar icon) depending on enabled.

See also
void QPlatformWindow::setFrameStrutEventsEnabled ( bool  enabled)

Reimplement this method to set whether frame strut events should be sent to enabled.

See also
void QPlatformWindow::setGeometry ( const QRect rect)

This method is called whenever a window is moved or the window is resized. The resize can happen programmatically or by the window manager. This means there is no need to call this method directly from the window manager callback. Instead call QWindowSystemInterface::handleGeometryChange().

The position(x, y) part of rect might be inclusive or exclusive of the window frame as returned by frameMargins(). You can detect this in the plugin by checking qt_window_private(window())->positionPolicy.

bool QPlatformWindow::setKeyboardGrabEnabled ( bool  grab)

Sets the value of the property to grab.

void QPlatformWindow::setMask ( const QRegion region)

Reimplement if the platform supports shaping windows with a mask. Sets the mask of the current windows to region.

bool QPlatformWindow::setMouseGrabEnabled ( bool  grab)

Sets the value of the property to grab.

void QPlatformWindow::setOpacity ( qreal  level)

Reimplement if the platform supports transparent windows. Sets the opacity of the current windows to level.

void QPlatformWindow::setParent ( const QPlatformWindow *  parent)

This method is called to enable native child windows. When this method is called all geometry of this platform window will be relative to the parent.

void QPlatformWindow::setVisible ( bool  visible)

Reimplement this method in subclasses to show the surface if visible is true and hide the surface if visible is false. The default implementation sends a synchronous expose event.

void QPlatformWindow::setWindowFilePath ( const QString filePath)

Reimplement to set the window file path to filePath.

void QPlatformWindow::setWindowFlags ( Qt::WindowFlags  flags)

Sets the window flags of this surface to flags.

void QPlatformWindow::setWindowIcon ( const QIcon icon)

Reimplement to set the window icon to icon.

bool QPlatformWindow::setWindowModified ( bool  modified)

Returns true if the native window supports setting the modified flag, false otherwise.

void QPlatformWindow::setWindowState ( Qt::WindowState  state)

Requests setting the window state of this surface to type. Qt::WindowActive can be ignored.

void QPlatformWindow::setWindowTitle ( const QString title)

Reimplement to set the window title to title. The implementation might want to append the application display name to the window title.

See also
bool QPlatformWindow::startSystemResize ( const QPoint pos,
Qt::Corner  corner 

Reimplement to start a system size grip drag operation if the system supports it and return true to indicate success. It is called from the mouse press event handler of the size grip. The default implementation is empty and does nothing with pos and corner.

QWindow * QPlatformWindow::window ( ) const

Returns the window which belongs to the QPlatformWindow.

QSize QPlatformWindow::windowBaseSize ( ) const

Returns the QWindow base size.

QRectF QPlatformWindow::windowClosestAcceptableGeometry ( const QRectF nativeRect) const

Additional documentation pending.

void QPlatformWindow::windowEvent ( QEvent event)

Reimplement this method to be able to do any platform specific event handling. All events for window() are passed to this method before being sent to QWindow::event(). The default implementation does nothing with event.

QRect QPlatformWindow::windowFrameGeometry ( ) const

Returns the QWindow frame geometry.

QRect QPlatformWindow::windowGeometry ( ) const

Returns the QWindow geometry.

QSize QPlatformWindow::windowMaximumSize ( ) const

Returns the QWindow maximum size.

QSize QPlatformWindow::windowMinimumSize ( ) const

Returns the QWindow minimum size.

QSize QPlatformWindow::windowSizeIncrement ( ) const

Returns the QWindow size increment.

WId QPlatformWindow::winId ( ) const

Reimplement in subclasses to return a handle to the native window.