Adding some documentation for Lighthouse

The spirit here is "something is better than nothing". Ie. its the first
itteration of documenting the classes. No general Lighthouse
introduction yet...

1 files changed, 85 insertions, 4 deletions

diff --git a/src/gui/kernel/qplatformwindow_qpa.cpp b/src/gui/kernel/qplatformwindow_qpa.cpp
index 9d722d8..378fc68 100644
--- a/src/gui/kernel/qplatformwindow_qpa.cpp
+++ b/src/gui/kernel/qplatformwindow_qpa.cpp
@@ -51,6 +51,10 @@ class QPlatformWindowPrivate
     friend class QPlatformWindow;
 };
 
+/*!
+    Constructs a platform window with the given top level widget.
+*/
+
 QPlatformWindow::QPlatformWindow(QWidget *tlw)
     : d_ptr(new QPlatformWindowPrivate)
 {
@@ -59,22 +63,37 @@ QPlatformWindow::QPlatformWindow(QWidget *tlw)
     tlw->setPlatformWindow(this);
 }
 
+/*!
+    Virtual destructor does not delete its top level widget.
+*/
 QPlatformWindow::~QPlatformWindow()
 {
 }
 
+/*!
+    Returnes the widget which belongs to the QPlatformWindow
+*/
 QWidget *QPlatformWindow::widget() const
 {
     Q_D(const QPlatformWindow);
     return d->tlw;
 }
 
+/*!
+    This function is called by Qt whenever a window is moved or the window is resized. The resize
+    can happen programatically(from ie. user application) or by the window manager. This means that
+    there is no need to call this function specifically from the window manager callback, instead
+    call QWindowSystemInterface::handleGeometryChange(QWidget *w, const QRect &newRect);
+*/
 void QPlatformWindow::setGeometry(const QRect &rect)
 {
     Q_D(QPlatformWindow);
     d->rect = rect;
 }
 
+/*!
+    Returnes the current geometry of a window
+*/
 QRect QPlatformWindow::geometry() const
 {
     Q_D(const QPlatformWindow);
@@ -82,14 +101,16 @@ QRect QPlatformWindow::geometry() const
 }
 
 /*!
-Reimplemented in subclasses to show the surface if \a visible is \c true, and hide it if \a visible is \c false.
+    Reimplemented in subclasses to show the surface
+    if \a visible is \c true, and hide it if \a visible is \c false.
 */
 void QPlatformWindow::setVisible(bool visible)
 {
     Q_UNUSED(visible);
 }
 /*!
-Requests setting the window flags of this surface to \a type. Returns the actual flags set.
+    Requests setting the window flags of this surface
+    to \a type. Returns the actual flags set.
 */
 Qt::WindowFlags QPlatformWindow::setWindowFlags(Qt::WindowFlags flags)
 {
@@ -107,23 +128,83 @@ Qt::WindowFlags QPlatformWindow::windowFlags() const
     return d->flags;
 }
 
+/*!
+  Reimplement in subclasses to return a handle to the native window
+*/
 WId QPlatformWindow::winId() const { return WId(0); }
 
-void QPlatformWindow::setParent(const QPlatformWindow *) { qWarning("This plugin does not support setParent!"); }
+/*!
+    This function is called to enable native child widgets in QPA. It is common not to support this
+    feature in Window systems, but can be faked. When this function is called all geometry of this
+    platform window will be relative to the parent.
+*/
+//jl: It would be usefull to have a property on the platform window which indicated if the sub-class
+// supported the setParent. If not, then geometry would be in screen coordinates.
+void QPlatformWindow::setParent(const QPlatformWindow *parent)
+{
+    Q_UNUSED(parent);
+    qWarning("This plugin does not support setParent!");
+}
 
-void QPlatformWindow::setWindowTitle(const QString &) {}
+/*!
+  Reimplement to set the window title to \a title
+*/
+void QPlatformWindow::setWindowTitle(const QString &title) {}
 
+/*!
+  Reimplement to be able to let Qt rais windows to the top of the desktop
+*/
 void QPlatformWindow::raise() { qWarning("This plugin does not support raise()"); }
 
+/*!
+  Reimplement to be able to let Qt lower winows to the bottom of the dekstop
+*/
 void QPlatformWindow::lower() { qWarning("This plugin does not support lower()"); }
 
+/*!
+  Reimplement to be able to let Qt set the opacity level of a window
+*/
 void QPlatformWindow::setOpacity(qreal level)
 {
     Q_UNUSED(level);
     qWarning("This plugin does not support setting window opacity");
 }
 
+/*!
+  Reimplement to return the glContext assosiated with the window.
+*/
 QPlatformGLContext *QPlatformWindow::glContext() const
 {
     return 0;
 }
+
+/*!
+    \class QPlatformWindow
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+
+    \brief The QPlatformWindow class provides an abstraction for top-level windows.
+
+    The QPlatformWindow abstraction is used by QWidget for all its top level widgets. It is being
+    created by calling the createPlatformWindow function in the loaded QPlatformIntegration
+    instance.
+
+    QPlatformWindow is used to signal to the windowing system, how Qt persieves its frame.
+    However, it is not concerned with how Qt renders into the window it represents.
+
+    Top level QWidgets(tlw) will allways have a QPlatformWindow. However, it is not neccesary for
+    all tlw to have a QWindowSurface. This is the case for QGLWidget. And could be the case for
+    widgets where some  3.party renders into it.
+
+    The platform specific window handle can be retrieved by the winId function.
+
+    QPlatformWindow is also the way QPA defines how native child windows should be supported
+    through the setParent function.
+
+    The only way to retrieve a QPlatformGLContext in QPA is by calling the glContext() function
+    on QPlatformWindow.
+
+    \sa QWindowSurface, QWidget
+*/