Skip to content

PythonQt.QtCore.QFileSelector

QFileSelector

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

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.

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:

    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);

Similarly, if you want to pick a different data file based on target platform, your code might look something like this:

    QString defaultsPath = "data/defaults.conf";
#if defined(Q_OS_ANDROID)
    defaultsPath = "data/android/defaults.conf";
#elif defined(Q_OS_IOS)
    defaultsPath = "data/ios/defaults.conf";
#endif
    QFile defaults(defaultsPath);

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:

    QFileSelector selector;
    QFile defaultsFile(selector.select("data/defaults.conf"));

The files to be selected are placed in directories named with a '+' and a selector name. In the above example you could have the platform configurations selected by placing them in the following locations:

    data/defaults.conf
    data/+android/defaults.conf
    data/+ios/+en_GB/defaults.conf

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:

    images/background.png
    images/+android/+en_GB/background.png

With those files available, you would select a different file on the android platform, but only if the locale was en_GB.

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.

Adding Selectors

Selectors normally available are

  • platform, any of the following strings which match the platform the application is running on (list not exhaustive): android, ios, osx, darwin, mac, macos, linux, qnx, unix, windows. On Linux, if it can be determined, the name of the distribution too, like debian, fedora or opensuse.
  • locale, same as QLocale().name().

Further selectors will be added from the 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.

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:

  1. Selectors set via setExtraSelectors(), in the order they are in the list
  2. Selectors in the QT_FILE_SELECTORS environment variable, from left to right
  3. Locale
  4. Platform

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:

    images/background.png
    images/+linux/background.png
    images/+windows/background.png
    images/+admin/background.png
    images/+admin/+linux/background.png

Because extra selectors are checked before platform the +admin/background.png will be chosen on Windows when the admin selector is set, and +windows/background.png will be chosen on Windows when the admin selector is not set. On Linux, the +admin/+linux/background.png will be chosen when admin is set, and the +linux/background.png when it is not.

Source: https://doc.qt.io/archives/qt-5.15/qfileselector.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
allSelectors function (self) -> tuple X.allSelectors() -> tuple
blockSignals function (self, b: Any) -> bool X.blockSignals(b) -> bool (shared captured text)
childEvent function (self, event: Any) -> Any (shared captured text)
children function (self) -> tuple X.children() -> tuple (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
connect function (self, signal: Any, receiver: Any, slot: Any, type: Any) -> bool X.connect(signal, receiver, slot, type) -> bool (shared captured text)
customEvent function (self, event: Any) -> Any (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
deleteLater function (self) -> Any (shared captured text)
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QFileSelector.destroyed; argument details are not documented.
disconnect function (self, signal: Any, receiver: Any, slot: Any) -> bool X.disconnect(signal, receiver, slot) -> bool (shared captured text)
dumpObjectInfo function (self) -> Any (shared captured text)
dumpObjectTree function (self) -> Any (shared captured text)
dynamicPropertyNames function (self) -> Any (shared captured text)
event function (self, event: Any) -> bool X.event(event) -> bool (shared captured text)
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool (shared captured text)
extraSelectors function (self) -> tuple X.extraSelectors() -> tuple
findChild function (self, type: Any, name: Any) -> Any X.findChild(type, name) -> PythonQt.private.QObject (shared captured text)
findChildren function (self, type: Any, name: Any) -> tuple X.findChildren(type, name) -> tuple (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
installEventFilter function (self, filterObj: Any) -> Any (shared captured text)
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool (shared captured text)
isWidgetType function (self) -> bool X.isWidgetType() -> bool (shared captured text)
isWindowType function (self) -> bool X.isWindowType() -> bool (shared captured text)
killTimer function (self, id: Any) -> Any (shared captured text)
metaObject function (self) -> Any X.metaObject() -> PythonQt.QtCore.QMetaObject (shared captured text)
moveToThread function (self, thread: Any) -> Any (shared captured text)
objectName attribute Any (shared captured text)
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QFileSelector.objectNameChanged; argument details are not documented.
parent function (self) -> Any X.parent() -> PythonQt.private.QObject (shared captured text)
property function (self, name: Any) -> Any X.property(name) -> object (shared captured text)
removeEventFilter function (self, obj: Any) -> Any (shared captured text)
select function (self, filePath: Any) -> str X.select(filePath) -> str
sender function (self) -> Any X.sender() -> PythonQt.private.QObject (shared captured text)
senderSignalIndex function (self) -> int X.senderSignalIndex() -> int (shared captured text)
setExtraSelectors function (self, list: Any) -> None Sets the list of extra selectors which have been added programmatically to this instance.
setObjectName function (self, name: Any) -> Any (shared captured text)
setParent function (self, parent: Any) -> Any (shared captured text)
setProperty function (self, name: Any, value: Any) -> bool X.setProperty(name, value) -> bool (shared captured text)
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
startTimer function (self, interval: Any, timerType: Any) -> int X.startTimer(interval, timerType) -> int (shared captured text)
thread function (self) -> Any (shared captured text)
timerEvent function (self, event: Any) -> Any (shared captured text)
tr function (self, text: Any, ambig: Any, n: Any) -> str X.tr(text, ambig, n) -> str (shared captured text)