<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Support for QSettings — PyQt 4.10.3 Reference Guide</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '4.10.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/logo_tn.ico"/>
<link rel="top" title="PyQt 4.10.3 Reference Guide" href="index.html" />
<link rel="next" title="Integrating Python and QML" href="qml.html" />
<link rel="prev" title="Python Objects and QVariant" href="pyqt_qvariant.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="qml.html" title="Integrating Python and QML"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pyqt_qvariant.html" title="Python Objects and QVariant"
accesskey="P">previous</a> |</li>
<li><a href="index.html">PyQt 4.10.3 Reference Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="support-for-qsettings">
<h1>Support for QSettings<a class="headerlink" href="#support-for-qsettings" title="Permalink to this headline">ΒΆ</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version v4.8.3.</span></p>
<p>Qt provies the <tt class="docutils literal"><span class="pre">QSettings</span></tt> class as a platform independent API for the
persistent storage and retrieval of application settings. Settings are
retrieved using the <tt class="docutils literal"><span class="pre">QSettings.value()</span></tt> method which, when using v1 of
PyQt4’s <tt class="docutils literal"><span class="pre">QVariant</span></tt> API returns a <tt class="docutils literal"><span class="pre">QVariant</span></tt> object. An application will
then typically convert the <tt class="docutils literal"><span class="pre">QVariant</span></tt> to the appropriate fundamental type
using <tt class="docutils literal"><span class="pre">QVariant.toBool()</span></tt>, <tt class="docutils literal"><span class="pre">QVariant.toInt()</span></tt>.</p>
<p>The explicit use of these conversion methods works around a problem with the
way different platforms implement the storage of settings. Some platforms only
ever store string values which means that the type of the original value is
lost. Explicitly calling a conversion method provides the missing type
information about the value being retrieved.</p>
<p>A problem then arises when v2 of the <tt class="docutils literal"><span class="pre">QVariant</span></tt> API is used (i.e. the default
for Python v3) because those explicit conversion methods are not available.
Therefore a setting with an integer value of <tt class="docutils literal"><span class="pre">42</span></tt> may be retrieved as a
string value of <tt class="docutils literal"><span class="pre">'42'</span></tt>. This inconsistency is made worse by being platform
specific.</p>
<p>As a solution to the problem PyQt4’s implementation of <tt class="docutils literal"><span class="pre">QSettings.value()</span></tt>
takes an optional third argument called <tt class="docutils literal"><span class="pre">type</span></tt>. This is either a Python type
object, e.g. <tt class="docutils literal"><span class="pre">int</span></tt>, or a string that is the name of a C++ type, e.g.
<tt class="docutils literal"><span class="pre">'QStringList'</span></tt>. The value returned will be an object of the requested type.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="kn">import</span> <span class="n">QSettings</span><span class="p">,</span> <span class="n">QPoint</span>
<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">)</span>
<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">'int_value'</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>
<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">'point_value'</span><span class="p">,</span> <span class="n">QPoint</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">12</span><span class="p">))</span>
<span class="c"># This will write the setting to the platform specific storage.</span>
<span class="k">del</span> <span class="n">settings</span>
<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">)</span>
<span class="n">int_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">'int_value'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">"int_value: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">int_value</span><span class="p">))</span>
<span class="n">point_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">'point_value'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">QPoint</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">"point_value: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">point_value</span><span class="p">))</span>
</pre></div>
</div>
<p>When this is executed then the following will be displayed for all platforms:</p>
<div class="highlight-python"><pre>int_value: 42
point_value: PyQt4.QtCore.QPoint(10, 20)</pre>
</div>
<p>If the value of the setting is a container (corresponding to either
<tt class="docutils literal"><span class="pre">QVariantList</span></tt>, <tt class="docutils literal"><span class="pre">QVariantMap</span></tt> or <tt class="docutils literal"><span class="pre">QVariantHash</span></tt>) then the type is applied
to the contents of the container.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="kn">import</span> <span class="n">QSettings</span>
<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">)</span>
<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">'list_value'</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">'dict_value'</span><span class="p">,</span> <span class="p">{</span><span class="s">'one'</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">'two'</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>
<span class="c"># This will write the setting to the platform specific storage.</span>
<span class="k">del</span> <span class="n">settings</span>
<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">)</span>
<span class="n">list_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">'list_value'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">"list_value: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">list_value</span><span class="p">))</span>
<span class="n">dict_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">'dict_value'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">"dict_value: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">dict_value</span><span class="p">))</span>
</pre></div>
</div>
<p>When this is executed then the following will be displayed for all platforms:</p>
<div class="highlight-python"><pre>list_value: [1, 2, 3]
dict_value: {'one': 1, 'two': 2}</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<h4>Previous topic</h4>
<p class="topless"><a href="pyqt_qvariant.html"
title="previous chapter">Python Objects and QVariant</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="qml.html"
title="next chapter">Integrating Python and QML</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="qml.html" title="Integrating Python and QML"
>next</a> |</li>
<li class="right" >
<a href="pyqt_qvariant.html" title="Python Objects and QVariant"
>previous</a> |</li>
<li><a href="index.html">PyQt 4.10.3 Reference Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2013 Riverbank Computing Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
