Use QtPlatformHeaders to set platform specific functionality

This involves exposing a new function in the QPlatformNativeInterface
which gets a public function for QGuiApplication

Proof of concept is done through implementing _NET_WM_WINDOW_TYPE
setters for xcb

Change-Id: Ic9544e775fb71cc9b30273595ec41b1cdb1c9d64
Reviewed-by: Laszlo Agocs <laszlo.agocs@digia.com>

3 files changed, 78 insertions, 1 deletions

diff --git a/src/platformheaders/doc/qtplatformheaders.qdocconf b/src/platformheaders/doc/qtplatformheaders.qdocconf
index dfef69f892..65fe660b40 100644
--- a/src/platformheaders/doc/qtplatformheaders.qdocconf
+++ b/src/platformheaders/doc/qtplatformheaders.qdocconf
@@ -12,7 +12,9 @@ project = QtPlatformHeaders
 
 headerdirs  += ..
 sourcedirs  += ..
-exampledirs += ..
+exampledirs += .. \
+               snippets
+
 imagedirs   += images
 
 depends += qtdoc qtcore qtgui qtwidgets
diff --git a/src/platformheaders/doc/snippets/qxcbwindowfunctions/main.cpp b/src/platformheaders/doc/snippets/qxcbwindowfunctions/main.cpp
new file mode 100644
index 0000000000..d4cb965bda
--- /dev/null
+++ b/src/platformheaders/doc/snippets/qxcbwindowfunctions/main.cpp
@@ -0,0 +1,61 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtWidgets>
+#include <QtPlatformHeaders/qxcbwindowfunctions.h>
+
+//! [0]
+int main(int argc, char **argv)
+{
+    QApplication app(argc, argv);
+
+    QPushButton topLevelWidget("Hello World!");
+    topLevelWidget.winId(); //have to create the QWindow
+
+    QWindow *tlwWindow = topLevelWidget.windowHandle();
+
+    QXcbWindowFunctions::setWmWindowType(tlwWindow, QXcbWindowFunctions::Dock);
+
+    topLevelWidget.show();
+
+    return app.exec();
+}
+//! [0]
+
diff --git a/src/platformheaders/doc/src/qtplatformheaders.qdoc b/src/platformheaders/doc/src/qtplatformheaders.qdoc
index 4ed740d296..74df288d3d 100644
--- a/src/platformheaders/doc/src/qtplatformheaders.qdoc
+++ b/src/platformheaders/doc/src/qtplatformheaders.qdoc
@@ -61,8 +61,22 @@
     platforms a different class will be used. These classes are all placed in
     the Qt Platform Headers module.
 
+    Platform headers can be used in conjunction with
+    QGuiApplication::platformFunction() to give a type safe interface to
+    platform specific functionality. It is possible for headers defined in
+    QtPlatformHeaders to define typedefs for functions that can be returned by
+    a platform plugin from QGuiApplication::platformFunction(). Headers in
+    QtPlatformHeaders can also implement wrapper functions for the function
+    pointer, giving a static function that can be called from any context after
+    the platform integration has been created. An implementation of this
+    pattern is QXcbWindowFunctions::setWmWindowType().  This function retrieves
+    a function pointer from QGuiApplication::platformFunction, and executes
+    that function if the requested function was returned.
+
     \note Similar to the other QPA APIs, there are no binary compatibility
     guarantees for these classes, meaning that an application using these
     classes is only guaranteed to work with the Qt version it was developed
     against. Unlike QPA however, source compatibility is guaranteed.
+
+    \sa QXcbWindowFunctions
  */