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...

8 files changed, 334 insertions, 9 deletions

diff --git a/src/gui/kernel/qplatformglcontext_qpa.cpp b/src/gui/kernel/qplatformglcontext_qpa.cpp
index 5ed1d3d..a450b33 100644
--- a/src/gui/kernel/qplatformglcontext_qpa.cpp
+++ b/src/gui/kernel/qplatformglcontext_qpa.cpp
@@ -95,12 +95,18 @@ void QPlatformGLContextPrivate::setCurrentContext(QPlatformGLContext *context)
     threadContext->context = context;
 }
 
+/*!
+  Returns the platformWindow which this QPlatformGLContext belongs to.
+*/
 QPlatformWindow *QPlatformGLContext::platformWindow() const
 {
     Q_D(const QPlatformGLContext);
     return d->platformWindow;
 }
 
+/*!
+  Returns the last context which called makeCurrent. This function is thread aware.
+*/
 const QPlatformGLContext* QPlatformGLContext::currentContext()
 {
     QPlatformGLThreadContext *threadContext = qplatformgl_context_storage.localData();
@@ -110,11 +116,17 @@ const QPlatformGLContext* QPlatformGLContext::currentContext()
     return 0;
 }
 
+/*!
+    All subclasses needs to specify the platformWindow. It can be a null window.
+*/
 QPlatformGLContext::QPlatformGLContext(QPlatformWindow *platformWindow)
     :d_ptr(new QPlatformGLContextPrivate(platformWindow))
 {
 }
 
+/*!
+  If this is the current context for the thread, doneCurrent is called
+*/
 QPlatformGLContext::~QPlatformGLContext()
 {
     if (QPlatformGLContext::currentContext() == this) {
@@ -123,26 +135,45 @@ QPlatformGLContext::~QPlatformGLContext()
 
 }
 
+
+/*!
+    Makes it possible to set the context which can be the default for making new contexts.
+*/
 void QPlatformGLContext::setDefaultSharedContext(QPlatformGLContext *sharedContext)
 {
     QPlatformGLContextPrivate::staticSharedContext = sharedContext;
 }
 
+/*!
+    Default shared context is intended to be a globally awailable pointer to a context which can
+    be used for sharing resources when creating new contexts. Its default value is 0;
+*/
 const QPlatformGLContext *QPlatformGLContext::defaultSharedContext()
 {
     return QPlatformGLContextPrivate::staticSharedContext;
 }
 
+/*!
+    Reimplement in subclass to do makeCurrent on native GL context
+*/
 void QPlatformGLContext::makeCurrent()
 {
     QPlatformGLContextPrivate::setCurrentContext(this);
 }
 
+/*!
+    Reimplement in subclass to release current context.
+    Typically this is calling makeCurrent with 0 "surface"
+*/
 void QPlatformGLContext::doneCurrent()
 {
     QPlatformGLContextPrivate::setCurrentContext(0);
 }
 
+/*
+  internal: Needs to have a pointer to qGLContext. But since this is in QtGui we cant
+  have any type information.
+*/
 void *QPlatformGLContext::qGLContextHandle() const
 {
     Q_D(const QPlatformGLContext);
@@ -161,3 +192,42 @@ void QPlatformGLContext::deleteQGLContext()
     Q_D(QPlatformGLContext);
     d->qGLContextDeleteFunction(d->qGLContextHandle);
 }
+
+/*!
+    \class QPlatformGLContext
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+
+    \brief The QPlatformGLContext class provides an abstraction for native GL contexts.
+
+    In QPA the way to support OpenGL or OpenVG or other technologies that requires a native GL
+    context is through the QPlatformGLContext wrapper.
+
+    There is no factory function for QPlatformGLContexts, but rather only one accessor function.
+    The only place to retrieve a QPlatformGLContext from is through a QPlatformWindow.
+
+    The context which is current for a specific thread can be collected by the currentContext()
+    function. This is how QPlatformGLContext also makes it possible to use the QtOpenGL module
+    withhout using QGLWidget. When using QGLContext::currentContext(), it will ask
+    QPlatformGLContext for the currentContext. Then a corresponding QGLContext will be returned,
+    which maps to the QPlatformGLContext.
+*/
+
+/*! \fn void swapBuffers()
+    Reimplement in subclass to native swap buffers calls
+*/
+
+/*! getProcAddress(const QString& procName)
+    Reimplement in subclass to native getProcAddr calls.
+
+    Note: its convenient to use qPrintable(const QString &str) to get the const char * pointer
+*/
+
+/*! platformWindowFormat() const
+    QWidget has the function qplatformWindowFormat(). That function is for the application
+    programmer to request the format of the window and the context that he wants.
+
+    Reimplement this function in a subclass to indicate what format the glContext actually has.
+*/
diff --git a/src/gui/kernel/qplatformintegration_qpa.cpp b/src/gui/kernel/qplatformintegration_qpa.cpp
index e2a493d..2a9bf77 100644
--- a/src/gui/kernel/qplatformintegration_qpa.cpp
+++ b/src/gui/kernel/qplatformintegration_qpa.cpp
@@ -55,16 +55,35 @@ QPixmap QPlatformIntegration::grabWindow(WId window, int x, int y, int width, in
     return QPixmap();
 }
 
+/*!
+    Factory function for the eventloop integration interface.
+
+    Default implementation returns 0, which causes the eventloop to run in a single thread mode.
+
+    \sa QPlatformEventLoopIntegration
+*/
 QPlatformEventLoopIntegration *QPlatformIntegration::createEventLoopIntegration() const
 {
     return 0;
 }
 
+/*!
+    Returns wheter the given platform integration supports OpenGL.
+
+    Default implementation returns false,
+*/
 bool QPlatformIntegration::hasOpenGL() const
 {
     return false;
 }
 
+/*!
+    Accessor for the platform integrations fontdatabase.
+
+    Default implementation returns a default QPlatformFontDatabase.
+
+    \sa QPlatformFontDatabase
+*/
 QPlatformFontDatabase *QPlatformIntegration::fontDatabase() const
 {
     static QPlatformFontDatabase *db = 0;
@@ -74,4 +93,104 @@ QPlatformFontDatabase *QPlatformIntegration::fontDatabase() const
     return db;
 }
 
+/*!
+    \class QPlatformIntegration
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+    \brief The QPlatformIntegration class is the entry for WindowSystem specific functionality.
+
+    QPlatformIntegration is the single entry point for windowsystem specific functionality when
+    using the QPA platform. It has factory functions for creating platform specific pixmaps and
+    windows. The class also controlls the font subsystem.
+
+    QPlatformIntegration is a singelton class which gets instansiated in the QApplication
+    constructor. The QPlatformIntegration instance do not have ownership of objects it creates in
+    functions where the name starts with create. However, functions which don't have a name
+    starting with create acts as assessors to member variables.
+
+    It is not trivial to create or build a platform plugin outside of the Qt source tree. Therefor
+    the recommended approach for making new platform plugin is to copy an existing plugin inside
+    the QTSRCTREE/src/plugins/platform and develop the plugin inside the source tree.
+
+    The minimal platformintegration is the smallest platform integration it is possible to make,
+    which makes it an ideal starting point for new plugins. For a slightly more advanced plugin,
+    consider reviewing the directfb plugin, or the testlite plugin.
+*/
+
+/*!
+    \fn QPixmapData *createPixmapData(QPixmapData::PixelType type) const
+
+    Factory function for QPixmapData. PixelType can be either PixmapType or BitmapType.
+    \sa QPixmapData
+*/
+
+/*!
+    \fn QPlatformWindow *createPlatformWindow(QWidget *widget, WId winId = 0) const
+
+    Factory function for QPlatformWindow. The widget parameter is a pointer to the top level
+    widget(tlw) which the QPlatformWindow is suppose to be created for. The WId handle is actually
+    never used, but there for future reference. Its purpose is if it is going to be possible to
+    create QPlatformWindows on existing WId.
+
+    All tlw has to have a QPlatformWindow, and it will be created when the QPlatformWindow is set
+    to be visible for the first time. If the tlw's window flags are changed, or if the tlw's
+    QPlatformWindowFormat is changed, then the tlw's QPlatformWindow is deleted and a new one is
+    created.
+
+    \sa QPlatformWindow, QPlatformWindowFormat
+    \sa createWindowSurface(QWidget *widget, WId winId) const
+*/
+
+/*!
+    \fn QWindowSurface *createWindowSurface(QWidget *widget, WId winId) const
+
+    Factory function for QWindowSurface. The QWidget parameter is a pointer to the
+    top level widget(tlw) the window surface is created for. A QPlatformWindow is allways created
+    before the QWindowSurface for tlw where the widget also requires a WindowSurface. It is
+    possible to create top level QWidgets without a QWindowSurface by specifying
+    QPlatformWindowFormat::setWindowSurface(false) for the tlw QPlatformWindowFormat.
+
+    \sa QWindowSurface
+    \sa createPlatformWindow(QWidget *widget, WId winId = 0) const
+*/
+
+/*!
+    \fn void moveToScreen(QWidget *window, int screen)
+
+    This function is called when a QWidget is displayed on screen, or the QWidget is to be
+    displayed on a new screen. The QWidget parameter is a pointer to the top level widget and
+    the int parameter is the index to the screen in QList<QPlatformScreen *> screens() const.
+
+    Default implementation does nothing.
+
+    \sa screens() const
+*/
+
+/*!
+    \fn QList<QPlatformScreen *> screens() const
+
+    Accessor function to a list of all the screens on the current system. The screen with the
+    index == 0 is the default/main screen.
+*/
+
+/*!
+    \fn bool isVirtualDesktop()
+
+    Returns if the current windowing system configuration defines all the screens to be one
+    desktop(virtual desktop), or if each screen is a desktop of its own.
+
+    Default implementation returns false.
+*/
+
+/*!
+    \fn QPixmap grabWindow(WId window, int x, int y, int width, int height) const
+
+    This function is called when Qt needs to be able to grab the content of a window.
+
+    Returnes the content of the window specified with the WId handle within the boundaries of
+    QRect(x,y,width,height).
+*/
+
 QT_END_NAMESPACE
diff --git a/src/gui/kernel/qplatformintegration_qpa.h b/src/gui/kernel/qplatformintegration_qpa.h
index b1f4e5f..f01b4f4 100644
--- a/src/gui/kernel/qplatformintegration_qpa.h
+++ b/src/gui/kernel/qplatformintegration_qpa.h
@@ -69,10 +69,10 @@ public:
     virtual QPixmapData *createPixmapData(QPixmapData::PixelType type) const = 0;
     virtual QPlatformWindow *createPlatformWindow(QWidget *widget, WId winId = 0) const = 0;
     virtual QWindowSurface *createWindowSurface(QWidget *widget, WId winId) const = 0;
-    virtual void moveToScreen(QWidget *window, int screen) {Q_UNUSED(window); Q_UNUSED(screen);}
 
 // Window System functions
     virtual QList<QPlatformScreen *> screens() const = 0;
+    virtual void moveToScreen(QWidget *window, int screen) {Q_UNUSED(window); Q_UNUSED(screen);}
     virtual bool isVirtualDesktop() { return false; }
     virtual QPixmap grabWindow(WId window, int x, int y, int width, int height) const;
 
diff --git a/src/gui/kernel/qplatformscreen_qpa.cpp b/src/gui/kernel/qplatformscreen_qpa.cpp
index 478d2d6..5e80ba8 100644
--- a/src/gui/kernel/qplatformscreen_qpa.cpp
+++ b/src/gui/kernel/qplatformscreen_qpa.cpp
@@ -43,6 +43,12 @@
 #include <QtGui/qapplication.h>
 #include <QtGui/qdesktopwidget.h>
 
+/*!
+    Return the given top level widget for a given position.
+
+    Default implementation retrieves a list of all top level widgets and finds the first widget
+    which contains point \a pos
+*/
 QWidget *QPlatformScreen::topLevelAt(const QPoint & pos) const
 {
     QWidgetList list = QApplication::topLevelWidgets();
@@ -56,6 +62,13 @@ QWidget *QPlatformScreen::topLevelAt(const QPoint & pos) const
     return 0;
 }
 
+/*! \fn physicalSize() const
+    Reimplement in subclass to return the physical size of the screen. This function is used by
+    QFont to convert point sizes to pixel sizes.
+
+    Default implementation takes the pixel size of the screen, considers a dpi of 100 and returns
+    the calculated (and probably wrong) physical size
+*/
 QSize QPlatformScreen::physicalSize() const
 {
     static const int dpi = 100;
@@ -64,3 +77,38 @@ QSize QPlatformScreen::physicalSize() const
     return QSize(width,height);
 }
 
+/*!
+    \class QPlatformScreen
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+
+    \brief The QPlatformScreen class provides an abstraction for visual displays.
+
+    Many window systems has support for retrieving information on the attached displays. To be able
+    to query the display QPA uses QPlatformScreen. Qt its self is most dependent on the
+    physicalSize() function, since this is the function it uses to calculate the dpi to use when
+    converting point sizes to pixels sizes. However, this is unfortunate on some systems, as the
+    native system fakes its dpi size.
+
+    QPlatformScreen is also used by the public api QDesktopWidget for information about the desktop.
+ */
+
+/*! \fn geometry() const
+    Reimplement in subclass to return the pixel geometry of the screen
+*/
+
+/*! \fn availableGeometry() const
+    Reimplement in subclass to return the pixel geometry of the available space
+    This normally is the desktop screen minus the task manager, global menubar etc.
+*/
+
+/*! \fn depth() const
+    Reimplement in subclass to return current depth of the screen
+*/
+
+/*! \fn format() const
+    Reimplement in subclass to return the image format which corresponds to the screen format
+*/
+
diff --git a/src/gui/kernel/qplatformscreen_qpa.h b/src/gui/kernel/qplatformscreen_qpa.h
index 1704f0f..9080489 100644
--- a/src/gui/kernel/qplatformscreen_qpa.h
+++ b/src/gui/kernel/qplatformscreen_qpa.h
@@ -70,6 +70,7 @@ public:
     virtual int depth() const = 0;
     virtual QImage::Format format() const = 0;
     virtual QSize physicalSize() const;
+    //jl: should setDirty be removed.
     virtual void setDirty(const QRect &) {}
     virtual QWidget *topLevelAt(const QPoint &point) const;
 };
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
+*/
diff --git a/src/gui/kernel/qplatformwindow_qpa.h b/src/gui/kernel/qplatformwindow_qpa.h
index 6dfba05..90bc1cb 100644
--- a/src/gui/kernel/qplatformwindow_qpa.h
+++ b/src/gui/kernel/qplatformwindow_qpa.h
@@ -75,7 +75,7 @@ public:
     virtual WId winId() const;
     virtual void setParent(const QPlatformWindow *window);
 
-    virtual void setWindowTitle(const QString &);
+    virtual void setWindowTitle(const QString &title);
     virtual void raise();
     virtual void lower();
 
diff --git a/src/gui/kernel/qplatformwindowformat_qpa.cpp b/src/gui/kernel/qplatformwindowformat_qpa.cpp
index f0dad17..ade6bb3 100644
--- a/src/gui/kernel/qplatformwindowformat_qpa.cpp
+++ b/src/gui/kernel/qplatformwindowformat_qpa.cpp
@@ -102,9 +102,15 @@ public:
 /*!
     \class QPlatformWindowFormat
     \brief The QPlatformWindowFormat class specifies the display format of an OpenGL
-    rendering context.
+    rendering context and if possible attributes of the corresponding QPlatformWindow.
 
-    \ingroup painting-3D
+    \ingroup painting
+
+    QWidget has a setter and getter function for QPlatformWindowFormat. These functions can be used
+    by the application programmer to signal what kind of format he wants to the window and glcontext
+    should have. However, it is not allways possible to furfill these requirements. The application
+    programmer should therefor check the resulting QPlatformWindowFormat from QPlatformGLContext
+    to see the format that was actually created.
 
     A display format has several characteristics:
     \list
@@ -162,7 +168,7 @@ public:
         United States and other countries.
     \endlegalese
 
-    \sa QGLContext, QGLWidget
+    \sa QPlatformContext, QWidget
 */
 
 /*!