Doc: add an example how to create a flickable tab bar

Change-Id: Iad89f8d46b44ca2634d3f8ecd52431654ae5d7ac
Task-number: QTBUG-55129
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

3 files changed, 62 insertions, 0 deletions

diff --git a/src/imports/controls/doc/images/qtquickcontrols2-tabbar-flickable.png b/src/imports/controls/doc/images/qtquickcontrols2-tabbar-flickable.png
new file mode 100644
index 00000000..ede59233
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-tabbar-flickable.png
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-tabbar-flickable.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-tabbar-flickable.qml
new file mode 100644
index 00000000..2a4fac0e
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-tabbar-flickable.qml
@@ -0,0 +1,50 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.6
+import QtQuick.Controls 2.0
+
+Item {
+    width: 360
+    height: bar.height
+
+//! [1]
+TabBar {
+    id: bar
+    width: parent.width
+
+    Repeater {
+        model: ["First", "Second", "Third", "Fourth", "Fifth"]
+
+        TabButton {
+            text: modelData
+            width: Math.max(100, bar.width / 5)
+        }
+    }
+}
+//! [1]
+}
diff --git a/src/quicktemplates2/qquicktabbar.cpp b/src/quicktemplates2/qquicktabbar.cpp
index 9a3995ab..6fe734bb 100644
--- a/src/quicktemplates2/qquicktabbar.cpp
+++ b/src/quicktemplates2/qquicktabbar.cpp
@@ -60,6 +60,18 @@ QT_BEGIN_NAMESPACE
 
     \snippet qtquickcontrols2-tabbar.qml 1
 
+    \section2 Flickable Tabs
+
+    By default, TabBar resizes its buttons to fit the width of the control.
+    The available space is distributed equally to each button. The default
+    resizing behavior can be overridden by setting an explicit width for the
+    buttons. If the total width of the buttons exceeds the available width
+    of the tab bar, it automatically becomes flickable.
+
+    \image qtquickcontrols2-tabbar-flickable.png
+
+    \snippet qtquickcontrols2-tabbar-flickable.qml 1
+
     \sa TabButton, {Customizing TabBar}, {Navigation Controls}, {Container Controls}
 */