Qt 4.8
Public Types | Static Public Functions | List of all members
QDesktopServices Class Reference

The QDesktopServices class provides methods for accessing common desktop services. More...

#include <qdesktopservices.h>

Public Types

enum  StandardLocation {
  DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation,
  MusicLocation, MoviesLocation, PicturesLocation, TempLocation,
  HomeLocation, DataLocation, CacheLocation
}
 This enum describes the different locations that can be queried by QDesktopServices::storageLocation and QDesktopServices::displayName. More...
 

Static Public Functions

static QString displayName (StandardLocation type)
 Returns a localized display name for the given location type or an empty QString if no relevant location can be found. More...
 
static bool openUrl (const QUrl &url)
 Opens the given url in the appropriate Web browser for the user's desktop environment, and returns true if successful; otherwise returns false. More...
 
static void setUrlHandler (const QString &scheme, QObject *receiver, const char *method)
 Sets the handler for the given scheme to be the handler method provided by the receiver object. More...
 
static QString storageLocation (StandardLocation type)
 Returns the default system directory where files of type belong, or an empty string if the location cannot be determined. More...
 
static void unsetUrlHandler (const QString &scheme)
 Removes a previously set URL handler for the specified scheme. More...
 

Detailed Description

The QDesktopServices class provides methods for accessing common desktop services.

Since
4.2

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.

This class contains functions that provide simple interfaces to these services that indicate whether they succeeded or failed.

The openUrl() 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.

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.

URL Handlers

The behavior of the openUrl() function can be customized for individual URL schemes to allow applications to override the default handling behavior for certain types of URLs.

The dispatch mechanism allows only one custom handler to be used for each URL scheme; this is set using the setUrlHandler() function. Each handler is implemented as a slot which accepts only a single QUrl argument.

The existing handlers for each scheme can be removed with the unsetUrlHandler() function. This returns the handling behavior for the given scheme to the default behavior.

This system makes it easy to implement a help system, for example. Help could be provided in labels and text browsers using help://myapplication/mytopic URLs, and by registering a handler it becomes possible to display the help text inside the application:

class MyHelpHandler : public QObject
{
public:
...
public slots:
void showHelp(const QUrl &url);
};
QDesktopServices::setUrlHandler("help", helpInstance, "showHelp");

If inside the handler you decide that you can't open the requested URL, you can just call QDesktopServices::openUrl() again with the same argument, and it will try to open the URL using the appropriate mechanism for the user's desktop environment.

See also
QSystemTrayIcon, QProcess

Definition at line 59 of file qdesktopservices.h.

Enumerations

◆ StandardLocation

This enum describes the different locations that can be queried by QDesktopServices::storageLocation and QDesktopServices::displayName.

Since
4.4
  • DesktopLocation Returns the user's desktop directory.
  • DocumentsLocation Returns the user's document.
  • FontsLocation Returns the user's fonts.
  • ApplicationsLocation Returns the user's applications.
  • MusicLocation Returns the users music.
  • MoviesLocation Returns the user's movies.
  • PicturesLocation Returns the user's pictures.
  • TempLocation Returns the system's temporary directory.
  • HomeLocation Returns the user's home directory.
  • DataLocation Returns a directory location where persistent application data can be stored. QCoreApplication::applicationName and QCoreApplication::organizationName should work on all platforms.
  • CacheLocation Returns a directory location where user-specific non-essential (cached) data should be written.
See also
storageLocation() displayName()
Enumerator
DesktopLocation 
DocumentsLocation 
FontsLocation 
ApplicationsLocation 
MusicLocation 
MoviesLocation 
PicturesLocation 
TempLocation 
HomeLocation 
DataLocation 
CacheLocation 

Definition at line 66 of file qdesktopservices.h.

Functions

◆ displayName()

QString QDesktopServices::displayName ( StandardLocation  type)
static

Returns a localized display name for the given location type or an empty QString if no relevant location can be found.

Definition at line 109 of file qdesktopservices_blackberry.cpp.

Referenced by getFullPath(), launchWebBrowser(), and openDocument().

110 {
111  return storageLocation(type);
112 }
int type
Definition: qmetatype.cpp:239
static QString storageLocation(StandardLocation type)
Returns the default system directory where files of type belong, or an empty string if the location c...

◆ openUrl()

bool QDesktopServices::openUrl ( const QUrl url)
static

Opens the given url in the appropriate Web browser for the user's desktop environment, and returns true if successful; otherwise returns false.

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.

The following example opens a file on the Windows file system residing on a path that contains spaces:

QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode));

If a mailto 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 mailto links are handled by a Web browser.

For example, the following URL contains a recipient (user@.nosp@m.foo..nosp@m.com), a subject (Test), and a message body (Just a test):

mailto:user@foo.com?subject=Test&body=Just a test
Warning
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.
Note
On Symbian OS, SwEvent capability is required to open the given url if the Web browser is already running.
See also
setUrlHandler()

Definition at line 190 of file qdesktopservices.cpp.

Referenced by QTextBrowserPrivate::_q_activateAnchor(), QTextControlPrivate::activateLinkUnderCursor(), and QDeclarativeEnginePrivate::desktopOpenUrl().

191 {
192  QOpenUrlHandlerRegistry *registry = handlerRegistry();
193  QMutexLocker locker(&registry->mutex);
194  static bool insideOpenUrlHandler = false;
195 
196  if (!insideOpenUrlHandler) {
198  if (handler != registry->handlers.constEnd()) {
199  insideOpenUrlHandler = true;
200  bool result = QMetaObject::invokeMethod(handler->receiver, handler->name.constData(), Qt::DirectConnection, Q_ARG(QUrl, url));
201  insideOpenUrlHandler = false;
202  return result; // ### support bool slot return type
203  }
204  }
205 
206  bool result;
207  if (url.scheme() == QLatin1String("file"))
208  result = openDocument(url);
209  else
210  result = launchWebBrowser(url);
211 
212  return result;
213 }
const_iterator ConstIterator
Qt-style synonym for QHash::const_iterator.
Definition: qhash.h:474
#define Q_ARG(type, data)
Definition: qobjectdefs.h:246
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
The QUrl class provides a convenient interface for working with URLs.
Definition: qurl.h:61
const_iterator constFind(const Key &key) const
Returns an iterator pointing to the item with the key in the hash.
Definition: qhash.h:859
static bool openDocument(const QUrl &file)
static bool launchWebBrowser(const QUrl &url)
const_iterator constEnd() const
Returns a const STL-style iterator pointing to the imaginary item after the last item in the hash...
Definition: qhash.h:469
QString scheme() const
Returns the scheme of the URL.
Definition: qurl.cpp:4550
The QMutexLocker class is a convenience class that simplifies locking and unlocking mutexes...
Definition: qmutex.h:101
static bool invokeMethod(QObject *obj, const char *member, Qt::ConnectionType, QGenericReturnArgument ret, QGenericArgument val0=QGenericArgument(0), QGenericArgument val1=QGenericArgument(), QGenericArgument val2=QGenericArgument(), QGenericArgument val3=QGenericArgument(), QGenericArgument val4=QGenericArgument(), QGenericArgument val5=QGenericArgument(), QGenericArgument val6=QGenericArgument(), QGenericArgument val7=QGenericArgument(), QGenericArgument val8=QGenericArgument(), QGenericArgument val9=QGenericArgument())
Invokes the member (a signal or a slot name) on the object obj.
QImageIOHandler * handler

◆ setUrlHandler()

void QDesktopServices::setUrlHandler ( const QString scheme,
QObject receiver,
const char *  method 
)
static

Sets the handler for the given scheme to be the handler method provided by the receiver object.

This function provides a way to customize the behavior of openUrl(). If openUrl() is called with a URL with the specified scheme then the given method on the receiver object is called instead of QDesktopServices launching an external application.

The provided method must be implemented as a slot that only accepts a single QUrl argument.

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 QDesktopServices does not take ownership of handlers, no objects are deleted when a handler is replaced.

Note that the handler will always be called from within the same thread that calls QDesktopServices::openUrl().

See also
openUrl(), unsetUrlHandler()

Definition at line 237 of file qdesktopservices.cpp.

238 {
239  QOpenUrlHandlerRegistry *registry = handlerRegistry();
240  QMutexLocker locker(&registry->mutex);
241  if (!receiver) {
242  registry->handlers.remove(scheme);
243  return;
244  }
246  h.receiver = receiver;
247  h.name = method;
248  registry->handlers.insert(scheme, h);
249  QObject::connect(receiver, SIGNAL(destroyed(QObject*)),
250  registry, SLOT(handlerDestroyed(QObject*)));
251 }
int remove(const Key &key)
Removes all the items that have the key from the hash.
Definition: qhash.h:784
#define SLOT(a)
Definition: qobjectdefs.h:226
The QObject class is the base class of all Qt objects.
Definition: qobject.h:111
iterator insert(const Key &key, const T &value)
Inserts a new item with the key and a value of value.
Definition: qhash.h:753
#define SIGNAL(a)
Definition: qobjectdefs.h:227
static bool connect(const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
Creates a connection of the given type from the signal in the sender object to the method in the rece...
Definition: qobject.cpp:2580
The QMutexLocker class is a convenience class that simplifies locking and unlocking mutexes...
Definition: qmutex.h:101

◆ storageLocation()

QString QDesktopServices::storageLocation ( StandardLocation  type)
static

Returns the default system directory where files of type belong, or an empty string if the location cannot be determined.

Since
4.4
Note
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.
On Symbian OS, ApplicationsLocation always point /sys/bin folder on the same drive with executable. FontsLocation always points to folder on ROM drive. Symbian OS does not have desktop concept, DesktopLocation returns same path as DocumentsLocation. 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.

Definition at line 70 of file qdesktopservices_blackberry.cpp.

Referenced by displayName(), getFullPath(), launchWebBrowser(), openDocument(), and QDeclarativeScriptEngine::QDeclarativeScriptEngine().

71 {
73  return QDir::tempPath();
75  return QDir::homePath() + QLatin1String("/Cache");
76 
77  QString path;
78 
79  const int index = QDir::homePath().lastIndexOf("/data");
80 
81  const QString sharedRoot = QDir::homePath().replace(index,
82  QDir::homePath().length() - index, "/shared");
83 
84  switch (type) {
85  case DataLocation:
86  case DesktopLocation:
87  case HomeLocation:
88  path = QDir::homePath();
89  break;
90  case DocumentsLocation:
91  path = sharedRoot + QLatin1String("/documents");
92  break;
93  case PicturesLocation:
94  path = sharedRoot + QLatin1String("/photos");
95  break;
96  case MusicLocation:
97  path = sharedRoot + QLatin1String("/music");
98  break;
99  case MoviesLocation:
100  path = sharedRoot + QLatin1String("/videos");
101  break;
102  default:
103  break;
104  }
105 
106  return path;
107 }
int type
Definition: qmetatype.cpp:239
QString & replace(int i, int len, QChar after)
Definition: qstring.cpp:2005
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
The QString class provides a Unicode character string.
Definition: qstring.h:83
static QString tempPath()
Returns the absolute path of the system&#39;s temporary directory.
Definition: qdir.cpp:1987
int lastIndexOf(QChar c, int from=-1, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
Definition: qstring.cpp:3000
quint16 index
static QString homePath()
Returns the absolute path of the user&#39;s home directory.
Definition: qdir.cpp:1942

◆ unsetUrlHandler()

void QDesktopServices::unsetUrlHandler ( const QString scheme)
static

Removes a previously set URL handler for the specified scheme.

See also
setUrlHandler()

Definition at line 258 of file qdesktopservices.cpp.

259 {
260  setUrlHandler(scheme, 0, 0);
261 }
static void setUrlHandler(const QString &scheme, QObject *receiver, const char *method)
Sets the handler for the given scheme to be the handler method provided by the receiver object...

The documentation for this class was generated from the following files: