<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QDesktopServices Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QDesktopServices Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1><p>The QDesktopServices class provides methods for accessing common
desktop services. <a href="#details">More...</a></p>
<h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qdesktopservices.html#StandardLocation-enum">StandardLocation</a></b> { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, ..., CacheLocation }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qdesktopservices.html#QDesktopServices">__init__</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qdesktopservices.html#QDesktopServices-2">__init__</a></b> (<i>self</i>, QDesktopServices)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />QString <b><a href="qdesktopservices.html#displayName">displayName</a></b> (StandardLocation <i>type</i>)</li><li><div class="fn" />bool <b><a href="qdesktopservices.html#openUrl">openUrl</a></b> (QUrl <i>url</i>)</li><li><div class="fn" /><b><a href="qdesktopservices.html#setUrlHandler">setUrlHandler</a></b> (QString <i>scheme</i>, QObject <i>receiver</i>, str <i>method</i>)</li><li><div class="fn" /><b><a href="qdesktopservices.html#setUrlHandler-2">setUrlHandler</a></b> (QString <i>scheme</i>, callable <i>method</i>)</li><li><div class="fn" />QString <b><a href="qdesktopservices.html#storageLocation">storageLocation</a></b> (StandardLocation <i>type</i>)</li><li><div class="fn" /><b><a href="qdesktopservices.html#unsetUrlHandler">unsetUrlHandler</a></b> (QString <i>scheme</i>)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QDesktopServices class provides methods for accessing common
desktop services.</p>
<p>Many desktop environments provide services that can be used by
applications to perform common tasks, such as opening a web page,
in a way that is both consistent and takes into account the user's
application preferences.</p>
<p>This class contains functions that provide simple interfaces to
these services that indicate whether they succeeded or failed.</p>
<p>The <a href="qdesktopservices.html#openUrl">openUrl</a>()
function is used to open files located at arbitrary URLs in
external applications. For URLs that correspond to resources on the
local filing system (where the URL scheme is "file"), a suitable
application will be used to open the file; otherwise, a web browser
will be used to fetch and display the file.</p>
<p>The user's desktop settings control whether certain executable
file types are opened for browsing, or if they are executed
instead. Some desktop environments are configured to prevent users
from executing files obtained from non-local URLs, or to ask the
user's permission before doing so.</p>
<a id="url-handlers" name="url-handlers" />
<h3>URL Handlers</h3>
<p>The behavior of the <a href="qdesktopservices.html#openUrl">openUrl</a>() function can be
customized for individual URL schemes to allow applications to
override the default handling behavior for certain types of
URLs.</p>
<p>The dispatch mechanism allows only one custom handler to be used
for each URL scheme; this is set using the <a href="qdesktopservices.html#setUrlHandler">setUrlHandler</a>() function.
Each handler is implemented as a slot which accepts only a single
<a href="qurl.html">QUrl</a> argument.</p>
<p>The existing handlers for each scheme can be removed with the
<a href="qdesktopservices.html#unsetUrlHandler">unsetUrlHandler</a>()
function. This returns the handling behavior for the given scheme
to the default behavior.</p>
<p>This system makes it easy to implement a help system, for
example. Help could be provided in labels and text browsers using
<b>help://myapplication/mytopic</b> URLs, and by registering a
handler it becomes possible to display the help text inside the
application:</p>
<pre class="cpp">
<span class="keyword">class</span> MyHelpHandler : <span class="keyword">public</span> <span class="type"><a href="qobject.html">QObject</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type">void</span> showHelp(<span class="keyword">const</span> <span class="type"><a href="qurl.html">QUrl</a></span> <span class="operator">&</span>url);
};
<span class="type">QDesktopServices</span><span class="operator">.</span><a href="qdesktopservices.html#setUrlHandler">setUrlHandler</a>(<span class="string">"help"</span><span class="operator">,</span> helpInstance<span class="operator">,</span> <span class="string">"showHelp"</span>);
</pre>
<p>If inside the handler you decide that you can't open the
requested URL, you can just call <a href="qdesktopservices.html#openUrl">QDesktopServices.openUrl</a>()
again with the same argument, and it will try to open the URL using
the appropriate mechanism for the user's desktop environment.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="StandardLocation-enum" />QDesktopServices.StandardLocation</h3><p>This enum describes the different locations that can be queried
by QDesktopServices.storageLocation and
QDesktopServices.displayName.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign">
<tt>QDesktopServices.DesktopLocation</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">Returns the user's desktop directory.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QDesktopServices.DocumentsLocation</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">Returns the user's document.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.FontsLocation</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">Returns the user's fonts.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QDesktopServices.ApplicationsLocation</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">Returns the user's applications.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.MusicLocation</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">Returns the users music.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.MoviesLocation</tt></td>
<td class="topAlign"><tt>5</tt></td>
<td class="topAlign">Returns the user's movies.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QDesktopServices.PicturesLocation</tt></td>
<td class="topAlign"><tt>6</tt></td>
<td class="topAlign">Returns the user's pictures.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.TempLocation</tt></td>
<td class="topAlign"><tt>7</tt></td>
<td class="topAlign">Returns the system's temporary directory.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.HomeLocation</tt></td>
<td class="topAlign"><tt>8</tt></td>
<td class="topAlign">Returns the user's home directory.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.DataLocation</tt></td>
<td class="topAlign"><tt>9</tt></td>
<td class="topAlign">Returns a directory location where persistent
application data can be stored. <a href="qcoreapplication.html#applicationName-prop">QCoreApplication.applicationName</a>
and <a href="qcoreapplication.html#organizationName-prop">QCoreApplication.organizationName</a>
should work on all platforms.</td>
</tr>
<tr>
<td class="topAlign"><tt>QDesktopServices.CacheLocation</tt></td>
<td class="topAlign"><tt>10</tt></td>
<td class="topAlign">Returns a directory location where
user-specific non-essential (cached) data should be written.</td>
</tr>
</table>
<p>This enum was introduced or modified in Qt 4.4.</p>
<p><b>See also</b> <a href="qdesktopservices.html#storageLocation">storageLocation</a>() and
<a href="qdesktopservices.html#displayName">displayName</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QDesktopServices" />QDesktopServices.__init__ (<i>self</i>)</h3><h3 class="fn"><a name="QDesktopServices-2" />QDesktopServices.__init__ (<i>self</i>, <a href="qdesktopservices.html">QDesktopServices</a>)</h3><h3 class="fn"><a name="displayName" />QString QDesktopServices.displayName (<a href="qdesktopservices.html#StandardLocation-enum">StandardLocation</a> <i>type</i>)</h3><p>Returns a localized display name for the given location
<i>type</i> or an empty <a href="qstring.html">QString</a> if no
relevant location can be found.</p>
<h3 class="fn"><a name="openUrl" />bool QDesktopServices.openUrl (<a href="qurl.html">QUrl</a> <i>url</i>)</h3><p>Opens the given <i>url</i> in the appropriate Web browser for
the user's desktop environment, and returns true if successful;
otherwise returns false.</p>
<p>If the URL is a reference to a local file (i.e., the URL scheme
is "file") then it will be opened with a suitable application
instead of a Web browser.</p>
<p>The following example opens a file on the Windows file system
residing on a path that contains spaces:</p>
<pre class="cpp">
<span class="type"><a href="qdesktopservices.html">QDesktopServices</a></span><span class="operator">.</span>openUrl(<span class="type"><a href="qurl.html">QUrl</a></span>(<span class="string">"file:///C:/Documents and Settings/All Users/Desktop"</span><span class="operator">,</span> <span class="type"><a href="qurl.html">QUrl</a></span><span class="operator">.</span>TolerantMode));
</pre>
<p>If a <tt>mailto</tt> URL is specified, the user's e-mail client
will be used to open a composer window containing the options
specified in the URL, similar to the way <tt>mailto</tt> links are
handled by a Web browser.</p>
<p>For example, the following URL contains a recipient
(<tt>user@foo.com</tt>), a subject (<tt>Test</tt>), and a message
body (<tt>Just a test</tt>):</p>
<pre class="cpp">
mailto:user@foo<span class="operator">.</span>com<span class="operator">?</span>subject<span class="operator">=</span>Test<span class="operator">&</span>body<span class="operator">=</span>Just a test
</pre>
<p><b>Warning:</b> Although many e-mail clients can send
attachments and are Unicode-aware, the user may have configured
their client without these features. Also, certain e-mail clients
(e.g., Lotus Notes) have problems with long URLs.</p>
<p><b>Note:</b> On Symbian OS, <tt>SwEvent</tt> capability is
required to open the given <i>url</i> if the Web browser is already
running.</p>
<p><b>See also</b> <a href="qdesktopservices.html#setUrlHandler">setUrlHandler</a>().</p>
<h3 class="fn"><a name="setUrlHandler" />QDesktopServices.setUrlHandler (QString <i>scheme</i>, <a href="qobject.html">QObject</a> <i>receiver</i>, str <i>method</i>)</h3><p>Sets the handler for the given <i>scheme</i> to be the handler
<i>method</i> provided by the <i>receiver</i> object.</p>
<p>This function provides a way to customize the behavior of
<a href="qdesktopservices.html#openUrl">openUrl</a>(). If <a href="qdesktopservices.html#openUrl">openUrl</a>() is called with a URL
with the specified <i>scheme</i> then the given <i>method</i> on
the <i>receiver</i> object is called instead of <a href="qdesktopservices.html">QDesktopServices</a> launching an external
application.</p>
<p>The provided method must be implemented as a slot that only
accepts a single <a href="qurl.html">QUrl</a> argument.</p>
<p>If setUrlHandler() is used to set a new handler for a scheme
which already has a handler, the existing handler is simply
replaced with the new one. Since <a href="qdesktopservices.html">QDesktopServices</a> does not take
ownership of handlers, no objects are deleted when a handler is
replaced.</p>
<p>Note that the handler will always be called from within the same
thread that calls <a href="qdesktopservices.html#openUrl">QDesktopServices.openUrl</a>().</p>
<p><b>See also</b> <a href="qdesktopservices.html#openUrl">openUrl</a>() and <a href="qdesktopservices.html#unsetUrlHandler">unsetUrlHandler</a>().</p>
<h3 class="fn"><a name="setUrlHandler-2" />QDesktopServices.setUrlHandler (QString <i>scheme</i>, callable <i>method</i>)</h3><h3 class="fn"><a name="storageLocation" />QString QDesktopServices.storageLocation (<a href="qdesktopservices.html#StandardLocation-enum">StandardLocation</a> <i>type</i>)</h3><p>Returns the default system directory where files of <i>type</i>
belong, or an empty string if the location cannot be
determined.</p>
<p><b>Note:</b> The storage location returned can be a directory
that does not exist; i.e., it may need to be created by the system
or the user.</p>
<p><b>Note:</b> On Symbian OS, <a href="qdesktopservices.html#StandardLocation-enum">ApplicationsLocation</a>
always point /sys/bin folder on the same drive with executable.
<a href="qdesktopservices.html#StandardLocation-enum">FontsLocation</a>
always points to folder on ROM drive. Symbian OS does not have
desktop concept, <a href="qdesktopservices.html#StandardLocation-enum">DesktopLocation</a>
returns same path as <a href="qdesktopservices.html#StandardLocation-enum">DocumentsLocation</a>.
Rest of the standard locations point to folder on same drive with
executable, except that if executable is in ROM the folder from C
drive is returned.</p>
<p>This function was introduced in Qt 4.4.</p>
<h3 class="fn"><a name="unsetUrlHandler" />QDesktopServices.unsetUrlHandler (QString <i>scheme</i>)</h3><p>Removes a previously set URL handler for the specified
<i>scheme</i>.</p>
<p><b>See also</b> <a href="qdesktopservices.html#setUrlHandler">setUrlHandler</a>().</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
