CopperSpice API  1.7.2
QPlatformWindow Class Reference

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

Inheritance diagram for QPlatformWindow:
QPlatformSurface

Public Methods

 QPlatformWindow (QWindow *window)
 
virtual ~QPlatformWindow ()
 
virtual qreal devicePixelRatio () const
 
virtual 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)
explicit

Constructs a platform window with the given top level window.

QPlatformWindow::~QPlatformWindow ( )
virtual

Virtual destructor does not delete the top level window.

Method Documentation

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

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)
staticprotected

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

qreal QPlatformWindow::devicePixelRatio ( ) const
virtual

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
QPlatformWindow::devicePixelRatio()
QSurfaceFormat QPlatformWindow::format ( ) const
overridevirtual

Returns the actual surface format of the window.

Implements QPlatformSurface.

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

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
virtual

Documentation pending.

bool QPlatformWindow::frameStrutEventsEnabled ( ) const
virtual

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

QRect QPlatformWindow::geometry ( ) const
virtual

Returns the current geometry of a window.

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

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
QWindow::reportContentOrientationChange()
QRect QPlatformWindow::initialGeometry ( const QWindow window,
const QRect initialGeometry,
int  defaultWidth,
int  defaultHeight 
)
static

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 ( )
virtual

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
virtual

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

bool QPlatformWindow::isAlertState ( ) const
virtual

Documentation pending.

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

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
virtual

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

void QPlatformWindow::lower ( )
virtual

Reimplement if the platform supports reordering windows.

QPoint QPlatformWindow::mapFromGlobal ( const QPoint pos) const
virtual

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
virtual

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
virtual

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 ( )
virtual

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

void QPlatformWindow::raise ( )
virtual

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

void QPlatformWindow::requestActivateWindow ( )
virtual

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 ( )
virtual

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

QPlatformWindow subclasses can re-implement this function to provide display refresh synchronized updates. The event should be delivered using QWindowPrivate::deliverUpdateRequest() to not get out of sync with the internal state of 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
protected

Helper function for finding 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.

See also
QWindowSystemInterface::handleWindowScreenChanged()
void QPlatformWindow::setAlertState ( bool  enabled)
virtual

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

See also
isAlertState()
void QPlatformWindow::setFrameStrutEventsEnabled ( bool  enabled)
virtual

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

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

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)
virtual

Sets the value of the property to grab.

void QPlatformWindow::setMask ( const QRegion region)
virtual

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

bool QPlatformWindow::setMouseGrabEnabled ( bool  grab)
virtual

Sets the value of the property to grab.

void QPlatformWindow::setOpacity ( qreal  level)
virtual

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

void QPlatformWindow::setParent ( const QPlatformWindow *  parent)
virtual

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)
virtual

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)
virtual

Reimplement to set the window file path to filePath.

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

Sets the window flags of this surface to flags.

void QPlatformWindow::setWindowIcon ( const QIcon icon)
virtual

Reimplement to set the window icon to icon.

bool QPlatformWindow::setWindowModified ( bool  modified)
virtual

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

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

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

void QPlatformWindow::setWindowTitle ( const QString title)
virtual

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

See also
QApplication::applicationDisplayName()
bool QPlatformWindow::startSystemResize ( const QPoint pos,
Qt::Corner  corner 
)
virtual

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

Documentation pending.

void QPlatformWindow::windowEvent ( QEvent event)
virtual

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
virtual

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