<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdesktopservices.cpp -->
<title>Qt 4.8: QDesktopServices Class Reference</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="modules.html">Modules</a></li>
<li><a href="qtgui.html">QtGui</a></li>
<li>QDesktopServices</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#static-public-members">Static Public Members</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#url-handlers">URL Handlers</a></li>
</ul>
</div>
<h1 class="title">QDesktopServices Class Reference</h1>
<!-- $$$QDesktopServices-brief -->
<p>The QDesktopServices class provides methods for accessing common desktop services. <a href="#details">More...</a></p>
<!-- @@@QDesktopServices -->
<pre class="cpp"> <span class="preprocessor">#include <QDesktopServices></span></pre><p>This class was introduced in Qt 4.2.</p>
<ul>
<li><a href="qdesktopservices-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2>Public Types</h2>
<table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qdesktopservices.html#StandardLocation-enum">StandardLocation</a></b> { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, ..., CacheLocation }</td></tr>
</table>
<a name="static-public-members"></a>
<h2>Static Public Members</h2>
<table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qdesktopservices.html#displayName">displayName</a></b> ( StandardLocation <i>type</i> )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qdesktopservices.html#openUrl">openUrl</a></b> ( const QUrl & <i>url</i> )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qdesktopservices.html#setUrlHandler">setUrlHandler</a></b> ( const QString & <i>scheme</i>, QObject * <i>receiver</i>, const char * <i>method</i> )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qdesktopservices.html#storageLocation">storageLocation</a></b> ( StandardLocation <i>type</i> )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qdesktopservices.html#unsetUrlHandler">unsetUrlHandler</a></b> ( const QString & <i>scheme</i> )</td></tr>
</table>
<a name="details"></a>
<!-- $$$QDesktopServices-description -->
<div class="descr">
<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 name="url-handlers"></a>
<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>
</div>
<p><b>See also </b><a href="qsystemtrayicon.html">QSystemTrayIcon</a> and <a href="qprocess.html">QProcess</a>.</p>
<!-- @@@QDesktopServices -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$StandardLocation$$$DesktopLocation$$$DocumentsLocation$$$FontsLocation$$$ApplicationsLocation$$$MusicLocation$$$MoviesLocation$$$PicturesLocation$$$TempLocation$$$HomeLocation$$$DataLocation$$$CacheLocation -->
<h3 class="fn"><a name="StandardLocation-enum"></a>enum QDesktopServices::<span class="name">StandardLocation</span></h3>
<p>This enum describes the different locations that can be queried by QDesktopServices::storageLocation and QDesktopServices::displayName.</p>
<table class="valuelist"><tr valign="top" class="odd"><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>
<!-- @@@StandardLocation -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$displayName[overload1]$$$displayNameStandardLocation -->
<h3 class="fn"><a name="displayName"></a><span class="type"><a href="qstring.html">QString</a></span> QDesktopServices::<span class="name">displayName</span> ( <span class="type"><a href="qdesktopservices.html#StandardLocation-enum">StandardLocation</a></span> <i>type</i> )<tt> [static]</tt></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>
<!-- @@@displayName -->
<!-- $$$openUrl[overload1]$$$openUrlconstQUrl& -->
<h3 class="fn"><a name="openUrl"></a><span class="type">bool</span> QDesktopServices::<span class="name">openUrl</span> ( const <span class="type"><a href="qurl.html">QUrl</a></span> & <i>url</i> )<tt> [static]</tt></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>
<!-- @@@openUrl -->
<!-- $$$setUrlHandler[overload1]$$$setUrlHandlerconstQString&QObject*constchar* -->
<h3 class="fn"><a name="setUrlHandler"></a><span class="type">void</span> QDesktopServices::<span class="name">setUrlHandler</span> ( const <span class="type"><a href="qstring.html">QString</a></span> & <i>scheme</i>, <span class="type"><a href="qobject.html">QObject</a></span> * <i>receiver</i>, const <span class="type">char</span> * <i>method</i> )<tt> [static]</tt></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>
<!-- @@@setUrlHandler -->
<!-- $$$storageLocation[overload1]$$$storageLocationStandardLocation -->
<h3 class="fn"><a name="storageLocation"></a><span class="type"><a href="qstring.html">QString</a></span> QDesktopServices::<span class="name">storageLocation</span> ( <span class="type"><a href="qdesktopservices.html#StandardLocation-enum">StandardLocation</a></span> <i>type</i> )<tt> [static]</tt></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>
<!-- @@@storageLocation -->
<!-- $$$unsetUrlHandler[overload1]$$$unsetUrlHandlerconstQString& -->
<h3 class="fn"><a name="unsetUrlHandler"></a><span class="type">void</span> QDesktopServices::<span class="name">unsetUrlHandler</span> ( const <span class="type"><a href="qstring.html">QString</a></span> & <i>scheme</i> )<tt> [static]</tt></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>
<!-- @@@unsetUrlHandler -->
</div>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
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.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
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. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
