com.trolltech.qt.gui
Class QDesktopServices

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.gui.QDesktopServices
All Implemented Interfaces:
QtJambiInterface

public class QDesktopServices
extends QtJambiObject

The QDesktopServices class provides methods for accessing common desktop services. 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:

        QDesktopServices.setUrlHandler("help", new QDesktopServices.UrlHandler() {
            public void handleUrl(QUrl url) {
                // respond to url...
            }
            });
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, and QProcess.


Nested Class Summary
static class QDesktopServices.StandardLocation
          This enum describes the different locations that can be queried by QDesktopServices.:storageLocation and QDesktopServices::displayName.
static interface QDesktopServices.UrlHandler
           
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QDesktopServices()
           
 
Method Summary
static java.lang.String displayName(QDesktopServices.StandardLocation type)
          Returns a localized display name for the given location type or an empty QString if no relevant location can be found.
static boolean openUrl(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.
static void setUrlHandler(java.lang.String scheme, QDesktopServices.UrlHandler urlHandler)
          Sets the handler for the given scheme to be the handler method provided by the receiver object.
static java.lang.String storageLocation(QDesktopServices.StandardLocation type)
          Returns the default system directory where files of type belong, or an empty string if the location cannot be determined.
static void unsetUrlHandler(java.lang.String scheme)
          Removes a previously set URL handler for the specified scheme.
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QDesktopServices

public QDesktopServices()
Method Detail

displayName

public static java.lang.String displayName(QDesktopServices.StandardLocation type)
Returns a localized display name for the given location type or an empty QString if no relevant location can be found.


openUrl

public static boolean openUrl(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.

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.

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@foo.com), a subject (Test), and a message body (Just a test):

    mailto:user@foo.com?subject=Testody=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.

See also:
setUrlHandler().


storageLocation

public static java.lang.String storageLocation(QDesktopServices.StandardLocation type)
Returns the default system directory where files of type belong, or an empty string if the location cannot be determined.

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.


unsetUrlHandler

public static void unsetUrlHandler(java.lang.String scheme)
Removes a previously set URL handler for the specified scheme.

See also:
setUrlHandler().


setUrlHandler

public static void setUrlHandler(java.lang.String scheme,
                                 QDesktopServices.UrlHandler urlHandler)
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().