Start to use QQuickFileSelector

* Doc in QQuickFileSelector was removed
* Replace QFileSelector with QQuickFileSelector
* Add "We mean it" in qquickfileselector_p.h

Change-Id: Idb7d8c9ce09300c8ada5d049db35de1c52760daf
Reviewed-by: J-P Nurmi <jpnurmi@theqtcompany.com>

5 files changed, 56 insertions, 211 deletions

diff --git a/src/imports/controls/controls.pri b/src/imports/controls/controls.pri
index 53615c08..41f25c45 100644
--- a/src/imports/controls/controls.pri
+++ b/src/imports/controls/controls.pri
@@ -28,9 +28,12 @@ QML_FILES = \
     Tumbler.qml
 
 HEADERS += \
+    $$PWD/qquickfileselector_p.h \
+    $$PWD/qquickfileselector_p_p.h \
     $$PWD/qquickthemedata_p.h \
     $$PWD/qquicktheme_p.h
 
 SOURCES += \
+    $$PWD/qquickfileselector.cpp \
     $$PWD/qquicktheme.cpp \
     $$PWD/qquickthemedata.cpp
diff --git a/src/imports/controls/qquickfileselector.cpp b/src/imports/controls/qquickfileselector.cpp
index 85d9b0bf..88bbf612 100644
--- a/src/imports/controls/qquickfileselector.cpp
+++ b/src/imports/controls/qquickfileselector.cpp
@@ -3,7 +3,7 @@
 ** Copyright (C) 2013 BlackBerry Limited. All rights reserved.
 ** Contact: http://www.qt.io/licensing/
 **
-** This file is part of the QtCore module of the Qt Toolkit.
+** This file is part of the Qt Labs Controls module of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL21$
 ** Commercial License Usage
@@ -31,8 +31,8 @@
 **
 ****************************************************************************/
 
-#include "qfileselector.h"
-#include "qfileselector_p.h"
+#include "qquickfileselector_p.h"
+#include "qquickfileselector_p_p.h"
 
 #include <QtCore/QFile>
 #include <QtCore/QDir>
@@ -46,182 +46,30 @@
 QT_BEGIN_NAMESPACE
 
 //Environment variable to allow tooling full control of file selectors
-static const char env_override[] = "QT_NO_BUILTIN_SELECTORS";
+static const char env_override[] = "QT_QUICK_NO_BUILTIN_SELECTORS";
 
 static const ushort selectorIndicator = '+';
 
-Q_GLOBAL_STATIC(QFileSelectorSharedData, sharedData);
+Q_GLOBAL_STATIC(QQuickFileSelectorSharedData, sharedData);
 static QBasicMutex sharedDataMutex;
 
-QFileSelectorPrivate::QFileSelectorPrivate()
+QQuickFileSelectorPrivate::QQuickFileSelectorPrivate()
     : QObjectPrivate()
 {
 }
 
-/*!
-    \class QFileSelector
-    \inmodule QtCore
-    \brief QFileSelector provides a convenient way of selecting file variants.
-    \since 5.2
-
-    QFileSelector is a convenience for selecting file variants based on platform or device
-    characteristics. This allows you to develop and deploy one codebase containing all the
-    different variants more easily in some circumstances, such as when the correct variant cannot
-    be determined during the deploy step.
-
-    \section1 Using QFileSelector
-
-    If you always use the same file you do not need to use QFileSelector.
-
-    Consider the following example usage, where you want to use different settings files on
-    different locales. You might select code between locales like this:
-
-    \code
-    QString defaultsBasePath = "data/";
-    QString defaultsPath = defaultsBasePath + "defaults.conf";
-    QString localizedPath = defaultsBasePath
-            + QString("%1/defaults.conf").arg(QLocale().name());
-    if (QFile::exists(localizedPath))
-        defaultsPath = localizedPath;
-    QFile defaults(defaultsPath);
-    \endcode
-
-    Similarly, if you want to pick a different data file based on target platform,
-    your code might look something like this:
-    \code
-    QString defaultsPath = "data/defaults.conf";
-#if defined(Q_OS_ANDROID)
-    defaultsPath = "data/android/defaults.conf";
-#elif defined(Q_OS_BLACKBERRY)
-    defaultsPath = "data/blackberry/defaults.conf";
-#elif defined(Q_OS_IOS)
-    defaultsPath = "data/ios/defaults.conf";
-#endif
-    QFile defaults(defaultsPath);
-    \endcode
-
-    QFileSelector provides a convenient alternative to writing such boilerplate code, and in the
-    latter case it allows you to start using an platform-specific configuration without a recompile.
-    QFileSelector also allows for chaining of multiple selectors in a convenient way, for example
-    selecting a different file only on certain combinations of platform and locale. For example, to
-    select based on platform and/or locale, the code is as follows:
-
-    \code
-    QFileSelector selector;
-    QFile defaultsFile(selector.select("data/defaults.conf"));
-    \endcode
-
-    The files to be selected are placed in directories named with a \c'+' and a selector name. In the above
-    example you could have the platform configurations selected by placing them in the following locations:
-    \code
-    data/defaults.conf
-    data/+android/defaults.conf
-    data/+blackberry/defaults.conf
-    data/+ios/+en_GB/defaults.conf
-    \endcode
-
-    To find selected files, QFileSelector looks in the same directory as the base file. If there are
-    any directories of the form +<selector> with an active selector, QFileSelector will prefer a file
-    with the same file name from that directory over the base file. These directories can be nested to
-    check against multiple selectors, for example:
-    \code
-    images/background.png
-    images/+android/+en_GB/background.png
-    images/+blackberry/+en_GB/background.png
-    \endcode
-    With those files available, you would select a different file on android and blackberry platforms,
-    but only if the locale was en_GB.
-
-    QFileSelector will not attempt to select if the base file does not exist. For error handling in
-    the case no valid selectors are present, it is recommended to have a default or error-handling
-    file in the base file location even if you expect selectors to be present for all deployments.
-
-    In a future version, some may be marked as deploy-time static and be moved during the
-    deployment step as an optimization. As selectors come with a performance cost, it is
-    recommended to avoid their use in circumstances involving performance-critical code.
-
-    \section1 Adding Selectors
-
-    Selectors normally available are
-    \list
-    \li platform, any of the following strings which match the platform the application is running
-        on (list not exhaustive): android, blackberry, ios, osx, darwin, mac, linux, wince, unix,
-        windows. On Linux, if it can be determined, the name of the distribution too, like debian,
-        fedora or opensuse.
-    \li locale, same as QLocale().name().
-    \endlist
-
-    Further selectors will be added from the \c QT_FILE_SELECTORS environment variable, which
-    when set should be a set of comma separated selectors. Note that this variable will only be
-    read once; selectors may not update if the variable changes while the application is running.
-    The initial set of selectors are evaluated only once, on first use.
-
-    You can also add extra selectors at runtime for custom behavior. These will be used in any
-    future calls to select(). If the extra selectors list has been changed, calls to select() will
-    use the new list and may return differently.
-
-    \section1 Conflict Resolution when Multiple Selectors Apply
-
-    When multiple selectors could be applied to the same file, the first matching selector is chosen.
-    The order selectors are checked in are:
-
-    \list 1
-    \li Selectors set via setExtraSelectors(), in the order they are in the list
-    \li Selectors in the \c QT_FILE_SELECTORS environment variable, from left to right
-    \li Locale
-    \li Platform
-    \endlist
-
-    Here is an example involving multiple selectors matching at the same time. It uses platform
-    selectors, plus an extra selector named "admin" is set by the application based on user
-    credentials. The example is sorted so that the lowest matching file would be chosen if all
-    selectors were present:
-
-    \code
-    images/background.png
-    images/+linux/background.png
-    images/+windows/background.png
-    images/+admin/background.png
-    images/+admin/+linux/background.png
-    \endcode
-
-    Because extra selectors are checked before platform the \c{+admin/background.png} will be chosen
-    on Windows when the admin selector is set, and \c{+windows/background.png} will be chosen on
-    Windows when the admin selector is not set.  On Linux, the \c{+admin/+linux/background.png} will be
-    chosen when admin is set, and the \c{+linux/background.png} when it is not.
-
-*/
-
-/*!
-    Create a QFileSelector instance. This instance will have the same static selectors as other
-    QFileSelector instances, but its own set of extra selectors.
-
-    If supplied, it will have the given QObject \a parent.
-*/
-QFileSelector::QFileSelector(QObject *parent)
-    : QObject(*(new QFileSelectorPrivate()), parent)
+QQuickFileSelector::QQuickFileSelector(QObject *parent)
+    : QObject(*(new QQuickFileSelectorPrivate()), parent)
 {
 }
 
-/*!
-  Destroys this selector instance.
-*/
-QFileSelector::~QFileSelector()
+QQuickFileSelector::~QQuickFileSelector()
 {
 }
 
-/*!
-   This function returns the selected version of the path, based on the conditions at runtime.
-   If no selectable files are present, returns the original \a filePath.
-
-   If the original file does not exist, the original \a filePath is returned. This means that you
-   must have a base file to fall back on, you cannot have only files in selectable sub-directories.
-
-   See the class overview for the selection algorithm.
-*/
-QString QFileSelector::select(const QString &filePath) const
+QString QQuickFileSelector::select(const QString &filePath) const
 {
-    Q_D(const QFileSelector);
+    Q_D(const QQuickFileSelector);
     return d->select(filePath);
 }
 
@@ -234,16 +82,9 @@ static bool isLocalScheme(const QString &file)
     return local;
 }
 
-/*!
-   This is a convenience version of select operating on QUrl objects. If the scheme is not file or qrc,
-   \a filePath is returned immediately. Otherwise selection is applied to the path of \a filePath
-   and a QUrl is returned with the selected path and other QUrl parts the same as \a filePath.
-
-   See the class overview for the selection algorithm.
-*/
-QUrl QFileSelector::select(const QUrl &filePath) const
+QUrl QQuickFileSelector::select(const QUrl &filePath) const
 {
-    Q_D(const QFileSelector);
+    Q_D(const QQuickFileSelector);
     if (!isLocalScheme(filePath.scheme()) && !filePath.isLocalFile())
         return filePath;
     QUrl ret(filePath);
@@ -283,9 +124,9 @@ static QString selectionHelper(const QString &path, const QString &fileName, con
     return path + fileName;
 }
 
-QString QFileSelectorPrivate::select(const QString &filePath) const
+QString QQuickFileSelectorPrivate::select(const QString &filePath) const
 {
-    Q_Q(const QFileSelector);
+    Q_Q(const QQuickFileSelector);
     QFileInfo fi(filePath);
     // If file doesn't exist, don't select
     if (!fi.exists())
@@ -299,44 +140,33 @@ QString QFileSelectorPrivate::select(const QString &filePath) const
     return filePath;
 }
 
-/*!
-    Returns the list of extra selectors which have been added programmatically to this instance.
-*/
-QStringList QFileSelector::extraSelectors() const
+QStringList QQuickFileSelector::extraSelectors() const
 {
-    Q_D(const QFileSelector);
+    Q_D(const QQuickFileSelector);
     return d->extras;
 }
 
-/*!
-    Sets the \a list of extra selectors which have been added programmatically to this instance.
-
-    These selectors have priority over any which have been automatically picked up.
-*/
-void QFileSelector::setExtraSelectors(const QStringList &list)
+void QQuickFileSelector::setExtraSelectors(const QStringList &list)
 {
-    Q_D(QFileSelector);
+    Q_D(QQuickFileSelector);
     d->extras = list;
 }
 
-/*!
-    Returns the complete, ordered list of selectors used by this instance
-*/
-QStringList QFileSelector::allSelectors() const
+QStringList QQuickFileSelector::allSelectors() const
 {
-    Q_D(const QFileSelector);
+    Q_D(const QQuickFileSelector);
     QMutexLocker locker(&sharedDataMutex);
-    QFileSelectorPrivate::updateSelectors();
+    QQuickFileSelectorPrivate::updateSelectors();
     return d->extras + sharedData->staticSelectors;
 }
 
-void QFileSelectorPrivate::updateSelectors()
+void QQuickFileSelectorPrivate::updateSelectors()
 {
     if (!sharedData->staticSelectors.isEmpty())
         return; //Already loaded
 
     QLatin1Char pathSep(',');
-    QStringList envSelectors = QString::fromLatin1(qgetenv("QT_FILE_SELECTORS"))
+    QStringList envSelectors = QString::fromLatin1(qgetenv("QT_QUICK_FILE_SELECTORS"))
                                 .split(pathSep, QString::SkipEmptyParts);
     if (envSelectors.count())
         sharedData->staticSelectors << envSelectors;
@@ -352,7 +182,7 @@ void QFileSelectorPrivate::updateSelectors()
     sharedData->staticSelectors << platformSelectors();
 }
 
-QStringList QFileSelectorPrivate::platformSelectors()
+QStringList QQuickFileSelectorPrivate::platformSelectors()
 {
     // similar, but not identical to QSysInfo::osType
     QStringList ret;
@@ -382,7 +212,7 @@ QStringList QFileSelectorPrivate::platformSelectors()
     return ret;
 }
 
-void QFileSelectorPrivate::addStatics(const QStringList &statics)
+void QQuickFileSelectorPrivate::addStatics(const QStringList &statics)
 {
     QMutexLocker locker(&sharedDataMutex);
     sharedData->preloadedStatics << statics;
@@ -390,4 +220,4 @@ void QFileSelectorPrivate::addStatics(const QStringList &statics)
 
 QT_END_NAMESPACE
 
-#include "moc_qfileselector.cpp"
+#include "moc_qquickfileselector_p.cpp"
diff --git a/src/imports/controls/qquickfileselector_p.h b/src/imports/controls/qquickfileselector_p.h
index 9ee35887..1a1cefc1 100644
--- a/src/imports/controls/qquickfileselector_p.h
+++ b/src/imports/controls/qquickfileselector_p.h
@@ -3,7 +3,7 @@
 ** Copyright (C) 2013 BlackBerry Limited. All rights reserved.
 ** Contact: http://www.qt.io/licensing/
 **
-** This file is part of the QtCore module of the Qt Toolkit.
+** This file is part of the Qt Labs Controls module of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL21$
 ** Commercial License Usage
@@ -34,18 +34,29 @@
 #ifndef QFILESELECTOR_H
 #define QFILESELECTOR_H
 
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API.  It exists purely as an
+// implementation detail.  This header file may change from version to
+// version without notice, or even be removed.
+//
+// We mean it.
+//
+
 #include <QtCore/QObject>
 #include <QtCore/QStringList>
 
 QT_BEGIN_NAMESPACE
 
-class QFileSelectorPrivate;
-class Q_CORE_EXPORT QFileSelector : public QObject
+class QQuickFileSelectorPrivate;
+class QQuickFileSelector : public QObject
 {
     Q_OBJECT
 public:
-    explicit QFileSelector(QObject *parent = Q_NULLPTR);
-    ~QFileSelector();
+    explicit QQuickFileSelector(QObject *parent = Q_NULLPTR);
+    ~QQuickFileSelector();
 
     QString select(const QString &filePath) const;
     QUrl select(const QUrl &filePath) const;
@@ -56,7 +67,7 @@ public:
     QStringList allSelectors() const;
 
 private:
-    Q_DECLARE_PRIVATE(QFileSelector)
+    Q_DECLARE_PRIVATE(QQuickFileSelector)
 };
 
 QT_END_NAMESPACE
diff --git a/src/imports/controls/qquickfileselector_p_p.h b/src/imports/controls/qquickfileselector_p_p.h
index 3fa327e3..1c06352f 100644
--- a/src/imports/controls/qquickfileselector_p_p.h
+++ b/src/imports/controls/qquickfileselector_p_p.h
@@ -3,7 +3,7 @@
 ** Copyright (C) 2013 BlackBerry Limited. All rights reserved.
 ** Contact: http://www.qt.io/licensing/
 **
-** This file is part of the QtCore module of the Qt Toolkit.
+** This file is part of the Qt Labs Controls module of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL21$
 ** Commercial License Usage
@@ -46,25 +46,26 @@
 //
 
 #include <QtCore/QString>
-#include <QtCore/QFileSelector>
 #include <private/qobject_p.h>
 
+#include "qquickfileselector_p.h"
+
 QT_BEGIN_NAMESPACE
 
-struct QFileSelectorSharedData //Not QSharedData because currently is just a global store
+struct QQuickFileSelectorSharedData //Not QSharedData because currently is just a global store
 {
     QStringList staticSelectors;
     QStringList preloadedStatics;
 };
 
-class Q_CORE_EXPORT QFileSelectorPrivate : QObjectPrivate //Exported for use in other modules (like QtGui)
+class QQuickFileSelectorPrivate : QObjectPrivate //Exported for use in other modules (like QtGui)
 {
-    Q_DECLARE_PUBLIC(QFileSelector)
+    Q_DECLARE_PUBLIC(QQuickFileSelector)
 public:
     static void updateSelectors();
     static QStringList platformSelectors();
     static void addStatics(const QStringList &); //For loading GUI statics from other Qt modules
-    QFileSelectorPrivate();
+    QQuickFileSelectorPrivate();
     QString select(const QString &filePath) const;
 
     QStringList extras;
diff --git a/src/imports/controls/qtlabscontrolsplugin.cpp b/src/imports/controls/qtlabscontrolsplugin.cpp
index 249375d2..f20ad630 100644
--- a/src/imports/controls/qtlabscontrolsplugin.cpp
+++ b/src/imports/controls/qtlabscontrolsplugin.cpp
@@ -35,12 +35,12 @@
 ****************************************************************************/
 
 #include <QtQml/qqmlextensionplugin.h>
-#include <QtCore/qfileselector.h>
 #include <QtCore/qurl.h>
 
 #include <QtLabsTemplates/private/qquickexclusivegroup_p.h>
 
 #include "qquicktheme_p.h"
+#include "qquickfileselector_p.h"
 
 void initResources()
 {
@@ -67,7 +67,7 @@ void QtLabsControlsPlugin::registerTypes(const char *uri)
     qmlRegisterType<QQuickExclusiveGroupAttached>();
 
     // TODO: read the style from application manifest file
-    QFileSelector selector;
+    QQuickFileSelector selector;
     QString base = baseUrl().toString();
     qmlRegisterType(selector.select(QUrl(base + QStringLiteral("/ApplicationWindow.qml"))), uri, 1, 0, "ApplicationWindow");
     qmlRegisterType(selector.select(QUrl(base + QStringLiteral("/BusyIndicator.qml"))), uri, 1, 0, "BusyIndicator");