<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qfileselector.cpp -->
<title>QFileSelector Class | Qt Core 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtcore-index.html">Qt Core</a></td><td ><a href="qtcore-module.html">C++ Classes</a></td><td >QFileSelector</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#using-qfileselector">Using QFileSelector</a></li>
<li class="level2"><a href="#adding-selectors">Adding Selectors</a></li>
<li class="level2"><a href="#conflict-resolution-when-multiple-selectors-apply">Conflict Resolution when Multiple Selectors Apply</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QFileSelector Class</h1>
<!-- $$$QFileSelector-brief -->
<p><a href="qfileselector.html">QFileSelector</a> provides a convenient way of selecting file variants. <a href="#details">More...</a></p>
<!-- @@@QFileSelector -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QFileSelector></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += core</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.2</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <a href="qobject.html">QObject</a></td></tr></table></div><ul>
<li><a href="qfileselector-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#QFileSelector">QFileSelector</a></b>(QObject *<i>parent</i> = Q_NULLPTR)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#dtor.QFileSelector">~QFileSelector</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#allSelectors">allSelectors</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#extraSelectors">extraSelectors</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#select">select</a></b>(const QString &<i>filePath</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QUrl </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#select-1">select</a></b>(const QUrl &<i>filePath</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qfileselector.html#setExtraSelectors">setExtraSelectors</a></b>(const QStringList &<i>list</i>)</td></tr>
</table></div>
<ul>
<li class="fn">32 public functions inherited from <a href="qobject.html#public-functions">QObject</a></li>
</ul>
<h3>Additional Inherited Members</h3>
<ul>
<li class="fn">1 property inherited from <a href="qobject.html#properties">QObject</a></li>
<li class="fn">1 public slot inherited from <a href="qobject.html#public-slots">QObject</a></li>
<li class="fn">2 signals inherited from <a href="qobject.html#signals">QObject</a></li>
<li class="fn">11 static public members inherited from <a href="qobject.html#static-public-members">QObject</a></li>
<li class="fn">9 protected functions inherited from <a href="qobject.html#protected-functions">QObject</a></li>
</ul>
<a name="details"></a>
<!-- $$$QFileSelector-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p><a href="qfileselector.html">QFileSelector</a> provides a convenient way of selecting file variants.</p>
<p><a href="qfileselector.html">QFileSelector</a> 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.</p>
<a name="using-qfileselector"></a>
<h3 >Using QFileSelector</h3>
<p>If you always use the same file you do not need to use <a href="qfileselector.html">QFileSelector</a>.</p>
<p>Consider the following example usage, where you want to use different settings files on different locales. You might select code between locales like this:</p>
<pre class="cpp">
<span class="type"><a href="qstring.html">QString</a></span> defaultsBasePath <span class="operator">=</span> <span class="string">"data/"</span>;
<span class="type"><a href="qstring.html">QString</a></span> defaultsPath <span class="operator">=</span> defaultsBasePath <span class="operator">+</span> <span class="string">"defaults.conf"</span>;
<span class="type"><a href="qstring.html">QString</a></span> localizedPath <span class="operator">=</span> defaultsBasePath
<span class="operator">+</span> <span class="type"><a href="qstring.html">QString</a></span>(<span class="string">"%1/defaults.conf"</span>)<span class="operator">.</span>arg(<span class="type"><a href="qlocale.html">QLocale</a></span>()<span class="operator">.</span>name());
<span class="keyword">if</span> (<span class="type"><a href="qfile.html">QFile</a></span><span class="operator">::</span>exists(localizedPath))
defaultsPath <span class="operator">=</span> localizedPath;
<span class="type"><a href="qfile.html">QFile</a></span> defaults(defaultsPath);
</pre>
<p>Similarly, if you want to pick a different data file based on target platform, your code might look something like this:</p>
<pre class="cpp">
<span class="type"><a href="qstring.html">QString</a></span> defaultsPath <span class="operator">=</span> <span class="string">"data/defaults.conf"</span>;
<span class="preprocessor">#if defined(Q_OS_ANDROID)</span>
defaultsPath <span class="operator">=</span> <span class="string">"data/android/defaults.conf"</span>;
<span class="preprocessor">#elif defined(Q_OS_IOS)</span>
defaultsPath <span class="operator">=</span> <span class="string">"data/ios/defaults.conf"</span>;
<span class="preprocessor">#endif</span>
<span class="type"><a href="qfile.html">QFile</a></span> defaults(defaultsPath);
</pre>
<p><a href="qfileselector.html">QFileSelector</a> 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. <a href="qfileselector.html">QFileSelector</a> 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:</p>
<pre class="cpp">
<span class="type"><a href="qfileselector.html#QFileSelector">QFileSelector</a></span> selector;
<span class="type"><a href="qfile.html">QFile</a></span> defaultsFile(selector<span class="operator">.</span>select(<span class="string">"data/defaults.conf"</span>));
</pre>
<p>The files to be selected are placed in directories named with a <code>'+'</code> and a selector name. In the above example you could have the platform configurations selected by placing them in the following locations:</p>
<pre class="cpp">
data<span class="operator">/</span>defaults<span class="operator">.</span>conf
data<span class="operator">/</span><span class="operator">+</span>android<span class="operator">/</span>defaults<span class="operator">.</span>conf
data<span class="operator">/</span><span class="operator">+</span>ios<span class="operator">/</span><span class="operator">+</span>en_GB<span class="operator">/</span>defaults<span class="operator">.</span>conf
</pre>
<p>To find selected files, <a href="qfileselector.html">QFileSelector</a> looks in the same directory as the base file. If there are any directories of the form +<selector> with an active selector, <a href="qfileselector.html">QFileSelector</a> 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:</p>
<pre class="cpp">
images<span class="operator">/</span>background<span class="operator">.</span>png
images<span class="operator">/</span><span class="operator">+</span>android<span class="operator">/</span><span class="operator">+</span>en_GB<span class="operator">/</span>background<span class="operator">.</span>png
</pre>
<p>With those files available, you would select a different file on the android platform, but only if the locale was en_GB.</p>
<p>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.</p>
<p>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.</p>
<a name="adding-selectors"></a>
<h3 >Adding Selectors</h3>
<p>Selectors normally available are</p>
<ul>
<li>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.</li>
<li>locale, same as QLocale().name().</li>
</ul>
<p>Further selectors will be added from the <code>QT_FILE_SELECTORS</code> 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.</p>
<p>You can also add extra selectors at runtime for custom behavior. These will be used in any future calls to <a href="qfileselector.html#select">select</a>(). If the extra selectors list has been changed, calls to <a href="qfileselector.html#select">select</a>() will use the new list and may return differently.</p>
<a name="conflict-resolution-when-multiple-selectors-apply"></a>
<h3 >Conflict Resolution when Multiple Selectors Apply</h3>
<p>When multiple selectors could be applied to the same file, the first matching selector is chosen. The order selectors are checked in are:</p>
<ol class="1" type="1"><li>Selectors set via <a href="qfileselector.html#setExtraSelectors">setExtraSelectors</a>(), in the order they are in the list</li>
<li>Selectors in the <code>QT_FILE_SELECTORS</code> environment variable, from left to right</li>
<li>Locale</li>
<li>Platform</li>
</ol>
<p>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:</p>
<pre class="cpp">
images<span class="operator">/</span>background<span class="operator">.</span>png
images<span class="operator">/</span><span class="operator">+</span>linux<span class="operator">/</span>background<span class="operator">.</span>png
images<span class="operator">/</span><span class="operator">+</span>windows<span class="operator">/</span>background<span class="operator">.</span>png
images<span class="operator">/</span><span class="operator">+</span>admin<span class="operator">/</span>background<span class="operator">.</span>png
images<span class="operator">/</span><span class="operator">+</span>admin<span class="operator">/</span><span class="operator">+</span>linux<span class="operator">/</span>background<span class="operator">.</span>png
</pre>
<p>Because extra selectors are checked before platform the <code>+admin/background.png</code> will be chosen on Windows when the admin selector is set, and <code>+windows/background.png</code> will be chosen on Windows when the admin selector is not set. On Linux, the <code>+admin/+linux/background.png</code> will be chosen when admin is set, and the <code>+linux/background.png</code> when it is not.</p>
</div>
<!-- @@@QFileSelector -->
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QFileSelector[overload1]$$$QFileSelectorQObject* -->
<h3 class="fn" id="QFileSelector"><a name="QFileSelector"></a>QFileSelector::<span class="name">QFileSelector</span>(<span class="type"><a href="qobject.html#QObject">QObject</a></span> *<i>parent</i> = Q_NULLPTR)</h3>
<p>Create a <a href="qfileselector.html">QFileSelector</a> instance. This instance will have the same static selectors as other <a href="qfileselector.html">QFileSelector</a> instances, but its own set of extra selectors.</p>
<p>If supplied, it will have the given <a href="qobject.html">QObject</a> <i>parent</i>.</p>
<!-- @@@QFileSelector -->
<!-- $$$~QFileSelector[overload1]$$$~QFileSelector -->
<h3 class="fn" id="dtor.QFileSelector"><a name="dtor.QFileSelector"></a>QFileSelector::<span class="name">~QFileSelector</span>()</h3>
<p>Destroys this selector instance.</p>
<!-- @@@~QFileSelector -->
<!-- $$$allSelectors[overload1]$$$allSelectors -->
<h3 class="fn" id="allSelectors"><a name="allSelectors"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QFileSelector::<span class="name">allSelectors</span>() const</h3>
<p>Returns the complete, ordered list of selectors used by this instance</p>
<!-- @@@allSelectors -->
<!-- $$$extraSelectors[overload1]$$$extraSelectors -->
<h3 class="fn" id="extraSelectors"><a name="extraSelectors"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QFileSelector::<span class="name">extraSelectors</span>() const</h3>
<p>Returns the list of extra selectors which have been added programmatically to this instance.</p>
<p><b>See also </b><a href="qfileselector.html#setExtraSelectors">setExtraSelectors</a>().</p>
<!-- @@@extraSelectors -->
<!-- $$$select[overload1]$$$selectconstQString& -->
<h3 class="fn" id="select"><a name="select"></a><span class="type"><a href="qstring.html">QString</a></span> QFileSelector::<span class="name">select</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>filePath</i>) const</h3>
<p>This function returns the selected version of the path, based on the conditions at runtime. If no selectable files are present, returns the original <i>filePath</i>.</p>
<p>If the original file does not exist, the original <i>filePath</i> is returned. This means that you must have a base file to fall back on, you cannot have only files in selectable sub-directories.</p>
<p>See the class overview for the selection algorithm.</p>
<!-- @@@select -->
<!-- $$$select$$$selectconstQUrl& -->
<h3 class="fn" id="select-1"><a name="select-1"></a><span class="type"><a href="qurl.html">QUrl</a></span> QFileSelector::<span class="name">select</span>(const <span class="type"><a href="qurl.html">QUrl</a></span> &<i>filePath</i>) const</h3>
<p>This is a convenience version of select operating on <a href="qurl.html">QUrl</a> objects. If the scheme is not file or qrc, <i>filePath</i> is returned immediately. Otherwise selection is applied to the path of <i>filePath</i> and a <a href="qurl.html">QUrl</a> is returned with the selected path and other <a href="qurl.html">QUrl</a> parts the same as <i>filePath</i>.</p>
<p>See the class overview for the selection algorithm.</p>
<!-- @@@select -->
<!-- $$$setExtraSelectors[overload1]$$$setExtraSelectorsconstQStringList& -->
<h3 class="fn" id="setExtraSelectors"><a name="setExtraSelectors"></a><span class="type">void</span> QFileSelector::<span class="name">setExtraSelectors</span>(const <span class="type"><a href="qstringlist.html">QStringList</a></span> &<i>list</i>)</h3>
<p>Sets the <i>list</i> of extra selectors which have been added programmatically to this instance.</p>
<p>These selectors have priority over any which have been automatically picked up.</p>
<p><b>See also </b><a href="qfileselector.html#extraSelectors">extraSelectors</a>().</p>
<!-- @@@setExtraSelectors -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
381
